workbench/classes/zune/aboutbox/MCC_Aboutbox.doc

   1 TABLE OF CONTENTS
   2
   3 Aboutbox.mcc/Aboutbox.mcc
   4 Aboutbox.mcc/MUIA_Aboutbox_Build
   5 Aboutbox.mcc/MUIA_Aboutbox_Credits
   6 Aboutbox.mcc/MUIA_Aboutbox_LogoData
   7 Aboutbox.mcc/MUIA_Aboutbox_LogoFallback
   8 Aboutbox.mcc/MUIA_Aboutbox_LogoFile
   9 \fAboutbox.mcc/Aboutbox.mcc
  10
  11    Aboutbox.mcc is a MUI custom class which offers a standardized 'About'
  12    and copyright information requester to achieve an uniform look across all
  13    applications which make use of it. It also reduces the amount of work
  14    required to  implement an own About requester.
  15
  16    To get the right look out of Aboutbox.mcc it is very important that
  17    the standard MUIA_Application_#? tags are properly filled and are style
  18    conform. Aboutbox will do some magic on them to retrieve the data
  19    it needs.
  20
  21    Setting the environment variable 'ABOUTBOX_DEBUG' will return verbose
  22    debug information in case information provided in the tag values are
  23    unsuitable.
  24
  25
  26    EXAMPLE
  27        myapp = ApplicationObject,
  28            MUIA_Application_Title,       "AboutboxDemo",
  29            MUIA_Application_Version,     "$VER: AboutboxDemo 1.0 (07.04.07)",
  30            MUIA_Application_Copyright,   "© 2007 Christian Rosentreter",
  31            MUIA_Application_Author,      "Christian Rosentreter",
  32            MUIA_Application_Description, "Demonstrates Aboutbox.mcc.",
  33        ...
  34
  35
  36    NOTES
  37    Do not add copyright information to the MUIA_Application_Version
  38    string. The style is:
  39
  40        "$VER: <app_title> <version>.<revision> (<dd>.<mm>.<yyyy>)"
  41
  42    A 2-digit year in the date is accepted too. Avoid adding weird information
  43    directly after the <app_title>. Do not use leading zeros for the re-
  44    vision (<version>.<revision> is not a decimal number; it's two numbers
  45    separated by a dot).
  46
  47
  48    If the project has multiple authors then a comma separated list can
  49    be used in MUIA_Application_Author, like: "Christian Rosentreter, Mister
  50    Banana", etc.
  51
  52    If the project requires multiple copyrights (e.g. because the Application
  53    was developed by someone else in the past) then a comma separated list can
  54    be used, too.
  55
  56    Avoid English and untranslatable words like: 'and', 'by', 'written by' and so
  57    on. Do not add 'Copyright' to the string, only use the ISO-Latin1 copyright
  58    sign ('©', hex: 0xa9). Aboutbox.mcc will automatically transform it to
  59    "Copyright ©" (or a localized variant) and also uses it to break the
  60    string into multiple lines. Accepted formats:
  61
  62        "© <year> <author1>"
  63        "© <year> <author1>, <author2>"
  64        "© <year> <author1>, © <year> <author2>"
  65        "© <year1>-<year2> <author>"
  66        etc.
  67
  68    Instead a single <year> a range like <year1>-<year2> can be used too.
  69    There must be a space after the copyright sign and before the <year>.
  70
  71
  72 \fAboutbox.mcc/MUIA_Aboutbox_Build
  73
  74    NAME
  75    MUIA_Aboutbox_Build -- (V20.10) [I..], STRPTR
  76
  77    FUNCTION
  78    Optional build information. Useful if the project is managed  via a
  79    revisions control software like Subversion. Build information is hidden by
  80    default, but can be viewed by clicking the version number in the Aboutbox
  81    window.
  82
  83
  84 \fAboutbox.mcc/MUIA_Aboutbox_Credits
  85
  86    NAME
  87    MUIA_Aboutbox_Credits -- (V20) [I..], STRPTR
  88
  89    FUNCTION
  90    Optional extra credits. If a valid string is passed then Aboutbox.mcc will
  91    add a second page to the requester and displays the information there. Currently
  92    the format of the string is limited to the ISO-8859-1 (Latin-1) character set.
  93
  94    Various  placeholders can be used to get predefined strings (or a
  95    localized equivalents):
  96
  97        %p - 'Programming:'
  98        %P - 'Additional programming:'
  99        %l - 'Translations:'
 100        %L - 'Proofreading:'
 101        %t - 'Thanks to:'
 102        %T - 'Special thanks to:'
 103        %a - 'Acknowledgements:'
 104        %d - 'Documentation:'
 105        %i - 'Icons:'
 106        %I - 'Icon:'                   (v20.10)
 107        %W - 'Web support:'
 108        %m - 'Music:'                  (v20.10)
 109        %s - 'Sound Effects'           (v20.10)
 110        %g - 'Graphics'                (v20.10)
 111        %? - 'Disclaimer'              (v20.10)
 112        %$ - 'License'                 (v20.10)
 113
 114    For printing an actual percent sign a double percent ('%%') can be used.
 115
 116    Tabs (\t) are replaced with 4 spaces. Further all normal MUI escaping sequences
 117    can be used without limitations. Lines in the string should preferably not be longer
 118    than 40 characters.
 119
 120    See the example for suggested layout.
 121
 122
 123    EXAMPLE
 124        STATIC CONST UBYTE credits[] =
 125             "\33b%p\33n\n"                 /* Programming: */
 126             "\tChristian Rosentreter\n"
 127             "\n"
 128             "\33b%l\33n\n"                 /* Translation: */
 129             "\tChristian Rosentreter\n"
 130             "\tMax Mustermann\n"
 131             "\tJohn Doe\n"
 132             "\tMr. Bean\n"
 133             "\n"
 134             "\33b%t\33n\n"                 /* Thanks to:   */
 135             "\tMax Mustermann\n"
 136             "\tJohn Doe";
 137
 138
 139 \fAboutbox.mcc/MUIA_Aboutbox_LogoData
 140
 141    NAME
 142    MUIA_Aboutbox_LogoData -- (V20.2) [I..], struct MUI_RawimageData *
 143
 144    FUNCTION
 145    Data pointer to into code embedded logo data in MUI_RawimageData format
 146    (see Rawimage.mcc documentation). The image must be exactly 64 pixels
 147    in width and 64 pixels in height. Other sizes are not supported.
 148
 149    NOTES
 150    This attribute should be avoided generally and not be used unless
 151    *absolutely* necessary. Aboutbox' default handling for the displayed
 152    logo is sufficient in 99.9% of all cases and any normal application
 153    usually doesn't require to overwrite it. This is reserved for some
 154    specific system components which require advanced special handling.
 155
 156    SEE ALSO
 157    MUIA_Aboutbox_LogoFallback, MUIA_Aboutbox_LogoFile,
 158    MUIA_Rawimage_Data
 159
 160 \fAboutbox.mcc/MUIA_Aboutbox_LogoFallback
 161
 162    NAME
 163    MUIA_Aboutbox_LogoFallback -- (V20.2) [I..], ULONG
 164
 165    FUNCTION
 166    Specify in which order default handling and fallback handlings to aquire
 167    correct logo data are executed.
 168
 169    Supported Specificators:
 170    D - default application icon (usually PROGDIR:<application>.info)
 171    E - file specified in MUIA_Aboutbox_LogoFile
 172    I - data specified with MUIA_Aboutbox_LogoData
 173
 174    The specificators can be merged in any order with the MAKE_ID() macro
 175    from "libraries/iffparse.h". The composed specification ID should be
 176    terminated with a '0' byte.
 177
 178    Defaults to MUIV_Aboutbox_LogoFallbackMode_Auto.
 179
 180    EXAMPLE
 181        /*  Let it first check for the application icon and if not
 182         *  available use an internal fallback logo.
 183         */
 184        aboutwindow = AboutboxObject,
 185            MUIA_Aboutbox_LogoFallback, MAKE_ID('D', 'I', '\0', '\0'),
 186            MUIA_Aboutbox_LogoData,     _internal_fallback_image_data,
 187        End;
 188
 189    NOTES
 190    This attribute should be avoided generally and not be used unless
 191    *absolutely* necessary. Aboutbox' default handling for the displayed
 192    logo is sufficient in 99.9% of all cases and any normal application
 193    usually doesn't require to overwrite it. This is reserved for some
 194    specific system components which require advanced special handling.
 195
 196    SEE ALSO
 197    MUIA_Aboutbox_LogoData, MUIA_Aboutbox_LogoFile
 198
 199 \fAboutbox.mcc/MUIA_Aboutbox_LogoFile
 200
 201    NAME
 202    MUIA_Aboutbox_LogoFile -- (V20.2) [I..], STRPTR
 203
 204    FUNCTION
 205    Specify an alternative location where to load the logo image from.
 206
 207    The image must be exactly 64 pixels in width and 64 pixels in height.
 208    Other sizes are not supported.
 209
 210    The path must be absolute. Relative paths are not supported. This makes
 211    it only useful for -and naturally limits it to- usage of fixed images
 212    or icons from a standard MorphOS system installation ('SYS:' or
 213    'MOSSYS:' paths).
 214
 215    NOTES
 216    This attribute should be avoided generally and not be used unless
 217    *absolutely* necessary. Aboutbox' default handling for the displayed
 218    logo is sufficient in 99.9% of all cases and any normal application
 219    usually doesn't require to overwrite it. This is reserved for some
 220    specific system components which require advanced special handling.
 221
 222    SEE ALSO
 223    MUIA_Aboutbox_LogoFallback, MUIA_Aboutbox_LogoData
 224