Style Guide - Revision history

JPV: Fixed capitalization on menu items.

2025-11-30T15:05:30Z

Fixed capitalization on menu items.

JPV at 10:06, 27 November 2025

2025-11-27T10:06:01Z

JPV at 07:40, 27 November 2025

2025-11-27T07:40:53Z

JPV at 14:53, 26 November 2025

2025-11-26T14:53:37Z

JPV: Created page with "''Author: Guido Mersmann'' This article presents fundamental recommendations for developing high-quality MorphOS software. Many applications do not fail because of missing fu..."

2025-11-26T13:14:58Z

Created page with "''Author: Guido Mersmann'' This article presents fundamental recommendations for developing high-quality MorphOS software. Many applications do not fail because of missing fu..."

New page

''Author: Guido Mersmann''

This article presents fundamental recommendations for developing high-quality MorphOS software. Many applications do not fail because of missing functionality, but because of details that negatively affect the user experience. The following guidelines help avoid common pitfalls and ensure that applications integrate consistently into the MorphOS environment.

== Structure of the Software Archive ==

A professional first impression begins with the structure of the distributed archive. A program should always be delivered inside its own directory without version numbers in the directory or file names. This makes handling software packages easier for both the user and the system.

Example:

The fictional tool ''Brawny'' is distributed as an archive named ''Brawny.lha'', containing a folder ''Brawny'' with all relevant files, including a program icon. Subfolders such as ''Help'' or language directories should each have their own .info file; purely system-related folders like ''Catalogs'' do not need one.

<nowiki>
Ram Disk:> lha x Brawny.lha

Extracting from archive 'Brawny.lha':
Extracting: ( 4716/ 4716) Brawny.info
Extracting: ( 6567813/ 6567813) Brawny/Brawny
Extracting: ( 30276/ 30276) Brawny/Brawny.info
Extracting: ( 54414/ 54414) Brawny/Brawny.readme
Extracting: ( 54/ 54) Brawny/Brawny.readme.info
5 files extracted, all files OK.</nowiki>

A clean archive structure improves access via both the Shell and the graphical Ambient interface.

== The Correct Version String ==

MorphOS requires a strictly defined format for version strings. Only when applications follow this standard can tools such as [[Shell_Commands/Version | Version]], package managers, or file comparison utilities work reliably.

Version string format:

$VER: <ApplicationName> <Version>.<Revision> (<DD.MM.YY>) © <Year AuthorName> <optional additional info>

Important notes:

* Version and revision consist of digits only.
* No letters or further sub-versions.
* The exact location in the program code is irrelevant, but it should appear early so it can be read quickly.

An incorrect version string can cause scripts or system tools to malfunction and should therefore be avoided at all costs.

== User Interface Principles ==

=== Localization ===

Supporting multiple languages should be standard practice today. MorphOS provides extensive mechanisms for this purpose, and developers should make use of them.

=== Labeling of UI Elements ===

* Labels for input elements should always end with a colon. This clearly indicates their association to the user.

=== Buttons and Ellipses ("...") ===

To distinguish between direct and indirect actions, a clear rule applies:

* Direct action: "Format" (action starts immediately)
* Indirect action: "Format..." (opens a new window or confirmation dialog first)

This convention increases predictability and safety for the user.

=== Checkboxes ===

* The text is always placed to the right of the checkbox.
* A uniform grid alignment creates a calm and consistent appearance.

=== Compact Interfaces ===

Even though modern systems support large screens, interfaces should remain scalable and fully usable on 1024×768 displays. MUI supports this largely automatically; nevertheless, developers should:

* avoid unnecessarily wide buttons and text fields.
* move explanatory content into tooltips if needed.

== Keyboard Shortcuts ==

Keyboard shortcuts improve operation speed and should be available everywhere. Especially in settings windows, language conventions apply: the underline is usually placed on the first letter of the term (e.g., Save: "S", Use: "U", Cancel: "C").

If the number of available letters is insufficient, the interface should be redesigned, or rarely used options placed in the context menu of a MUI object or in the screen menu.

== Screen Menus ==

=== Project vs. Application Menu ===

A Project menu is only appropriate if the application can actually load or save project files. Otherwise, the menu should simply use the application's name.

=== Settings ===

Every application should include a ''Settings'' menu, even if it has no custom options.

At minimum, it must contain the MUI entry, which provides access to the application's local UI settings.

=== About Window ===

MorphOS provides the Aboutbox.class, allowing developers to implement a uniform, professional about window with no extra effort.

=== Standard Key Combinations ===

There are established shortcuts (using the right Command key) that should be universal:

* Q -> Quit
* ? -> About
* P -> Print
* N -> New project
* O -> Open project
* S -> Save
* A -> Save As
* X -> Cut
* C -> Copy
* V -> Paste

As with buttons, if a menu entry opens a new window, it must end with "...".

== Learning from Existing MorphOS Programs ==

It is worthwhile to study applications included with the system. While not perfect, they generally implement UI conventions very well and serve as best-practice references for your own software.

== Summary ==

By consistently following a few clear design principles, MorphOS applications can be developed professionally and system-conformantly without significant extra effort. Clean archive organization, correct version strings, consistent user interfaces, and adherence to established conventions result in applications that integrate seamlessly into the system and feel immediately familiar to users.

← Older revision		Revision as of 10:06, 27 November 2025
Line 1:		Line 1:
−	~~''Author: Guido Mersmann''~~
−
	This article presents fundamental recommendations for developing high-quality MorphOS software. Many applications do not fail because of missing functionality, but because of details that negatively affect the user experience. The following guidelines help avoid common pitfalls and ensure that applications integrate consistently into the MorphOS environment.		This article presents fundamental recommendations for developing high-quality MorphOS software. Many applications do not fail because of missing functionality, but because of details that negatively affect the user experience. The following guidelines help avoid common pitfalls and ensure that applications integrate consistently into the MorphOS environment.

@@ Line 52: / Line 52: @@
 === Buttons and Ellipses ===
-To distinguish between direct and indirect actions, a clear rule applies:
+Ellipsis (three dots) is added to a button label to distinguish between direct and indirect actions.
 * Direct action:   "Format"     (action starts immediately)
 * Indirect action: "Format..." (opens a new window or confirmation dialog first)
@@ Line 58: / Line 60: @@
 This convention increases predictability and safety for the user.
 :: [[File:styleguide_buttons.png|frameless]]
 === Checkboxes ===
@@ Line 76: / Line 80: @@
 If the number of available letters is insufficient, the interface should be redesigned, or rarely used options placed in the context menu of a MUI object or in the screen menu.
-:: [[File:styleguide_shortcuts.png|frameless]]
+:: [[File:styleguide_shortcuts.png|332px|frameless]]
 == Screen Menus ==
@@ Line 113: / Line 117: @@
 === Direct and Indirect Actions ===
-As with buttons, if a menu entry opens a new window, it must end with "...".
+As with buttons, if a menu entry opens a new window, it must end with an ellipsis ("...").
 == Learning from Existing MorphOS Programs ==

@@ Line 105: / Line 105: @@
 * ? -> About
 * P -> Print
-* N -> New project
+* N -> New Project
-* O -> Open project
+* O -> Open Project
 * S -> Save
 * A -> Save As

@@ Line 41: / Line 41: @@
 == User Interface Principles ==
 === Localization ===
@@ Line 48: / Line 47: @@
 === Labeling of UI Elements ===
-* Labels for input elements should always end with a colon. This clearly indicates their association to the user.
+Labels for input elements should always end with a colon. This clearly indicates their association to the user.
-=== Buttons and Ellipses ("...") ===
+=== Buttons and Ellipses ===
 To distinguish between direct and indirect actions, a clear rule applies:
 * Direct action:   "Format"     (action starts immediately)
 * Indirect action: "Format..." (opens a new window or confirmation dialog first)
 This convention increases predictability and safety for the user.
 === Checkboxes ===
@@ Line 63: / Line 63: @@
 * The text is always placed to the right of the checkbox.
 * A uniform grid alignment creates a calm and consistent appearance.
 === Compact Interfaces ===
 Even though modern systems support large screens, interfaces should remain scalable and fully usable on 1024×768 displays. MUI supports this largely automatically; nevertheless, developers should:
 * avoid unnecessarily wide buttons and text fields.
 * move explanatory content into tooltips if needed.
@@ Line 76: / Line 76: @@
 If the number of available letters is insufficient, the interface should be redesigned, or rarely used options placed in the context menu of a MUI object or in the screen menu.
 == Screen Menus ==
@@ Line 82: / Line 83: @@
 A Project menu is only appropriate if the application can actually load or save project files. Otherwise, the menu should simply use the application's name.
 === Settings ===
@@ Line 88: / Line 90: @@
 At minimum, it must contain the MUI entry, which provides access to the application's local UI settings.
 === About Window ===
@@ Line 107: / Line 110: @@
 * C -> Copy
 * V -> Paste
 As with buttons, if a menu entry opens a new window, it must end with "...".