S Y M B O S   D E V E L O P E R   D O C U M E N T A T I O N
Author: Prodatron / Symbiosis
Date:   28.10.2005
===============================================================================

D E S K T O P   M A N A G E R   D A T A   R E C O R D S


WINDOWS

===============================================================================
WINDOW DATA RECORD
-------------------------------------------------------------------------------
00  1B  Status (0=closed, 1=normal, 2=maximized, 3=minimized)
01  1B  [bit0]=display 8x8 pixel application icon (in the upper left edge)
        [bit1]=window is resizeable
        [bit2]=display close button
        [bit3]=display tool bar (below the menu bar)
        [bit4]=display title bar
        [bit5]=display menu bar (below the title bar)
        [bit6]=display status bar (at the lower side of the window)
        [bit7]=*reserved*
02  1B  [bit0]=adjust x size of the window content to the x size of the window
        [bit1]=adjust y size of the window content to the y size of the window
        [bit2]=Window will not be displayed in the task bar
        [bit3]=Window is not moveable
        [bit4]=Window is a super window: other windows, who point on it (see
               byte 51), can't get the focus position
        [bit6]=*reserved*
        [bit7]=*reserved*
03  1B  Process ID of the windows owner
04  2W  x/y position, if window is not maximized
08  2W  x/y size, if window is not maximized
12  2W  x/y offset of the displayed window content
16  2W  full x/y length of the total window content
20  2W  minimal possible x/y size of the window
24  2W  maximal possible x/y size of the window
28  1W  address of the application icon (graphic object)
30  1W  address of the title line text (terminated by 0)
32  1W  address of the status line text (terminated by 0)
34  1W  address of the MENU DATA RECORD
36  1W  address of the CONTROL GROUP DATA RECORD of the window content
38  1W  address of the CONTROL GROUP DATA RECORD of the tool bar content
40  1W  height of the tool bar
42  9B  [*used during runtime, so it has to be reserved*]
51  1B  0 or number of super window + 1
52 140B [*used during runtime, so it has to be reserved*]

-------------------------------------------------------------------------------

===============================================================================
CONTROL GROUP DATA RECORD
-------------------------------------------------------------------------------
00  1B  number of controls (has to be >=1; notice that you have to fill the
        background of the form by yourself, too!)
01  1B  Process ID of the control group owner
02  1W  address of the CONTROL DATA RECORDS
04  1W  address of the position/size CALCULATION RULE DATA RECORD (0 means, no
        re-calculation)
06  2B  [*not used, set to 0*]
08  1B  object to click, when user hits return (1-255, 0=not defined)
09  1B  object to click, when user hits escape (1-255, 0=not defined)
10  4B  [*reserved, set to 0*]
14  1B  focus object (1-255, 0=no focus on any object)
15  1B  [*not used, set to 0*]
-------------------------------------------------------------------------------

===============================================================================
CONTROL DATA RECORDS
-------------------------------------------------------------------------------
[Number of controls] * [
00  1W  control ID/value; this will be sent to the application, if the user
        clicks or modifies the control. As an example you could store the
        address of a sub routine here, which you call, if the user clicks the
        control.
02  1B  CONTROL TYPE; for the type IDs see below. The IDs are between 0 and
        63. IDs > 63 will be ignored, so you can set bit 6 and/or 7 to 1, if
        you want to hide an object, and reset it to 0 if you want to show it
        again.
03  1B  bank number, where the extended control data record is located (0-8;
        -1 means, that the control is placed in the same bank like the window
        data record, so normally you can use -1 here)
04  1W  either a parameter to specify the control properties or, if one word is
        not enough, a pointer to the extended control data record; this depends
        on the control, so see the control description for information, what to
        write here.
06  2W  x/y position of the control (related to the upper left edge of the
        content or tool bar); if the window is using a CALCULATION RULE
        DATA RECORD, you can write 0 here
10  2W  x/y size of the control (related to the upper left edge of the content
        or tool bar); if the window is using a CALCULATION RULE DATA RECORD,
        you can write 0 here
14  2B  [*not used, set to 0*]
]
-------------------------------------------------------------------------------

===============================================================================
CALCULATION RULE DATA RECORD
-------------------------------------------------------------------------------
00  1W  x position (static part)
02  1B  window x size multiplier
03  1B  window x size divider
04  1W  y position (static part)
06  1B  window y size multiplier
07  1B  window y size divider
08  1W  x size (static part)
10  1B  window x size multiplier
12  1B  window x size divider
13  1W  y size (static part)
14  1B  window y size multiplier
15  1B  window y size divider

Description:
If "recalculation" for a control group is activated every coordinate and size
value of a control will be recalculated, if the user changes the size of the
window.
The calculation is:
position or size = static_part + window_size * multiplier / divider

Example:
centered_x_position = 0 + window_x_size * 1 / 2
quartered_y_size    = 0 + window_y_size * 1 / 4
-------------------------------------------------------------------------------



CONTROL TYPES

===============================================================================
PAINT
-------------------------------------------------------------------------------
ID:             00 (PLF)
Name:           paint_area
Parameter:      [bit0-1]=pen
Data record:    -
Size:           not limited
Description:    Fills an area with a specified colour.
-------------------------------------------------------------------------------
ID:             01 (PLT)
Name:           paint_text
Parameter:      pointer to data record
Data record:    00  1W  text address (terminated by 0)
                02  1B  [bit0-1]=paper, [bit2-3]=pen, [bit7]=if 1, fill backgr.
                03  1B  Alignment (0=left, 1=right, 2=center)
Size:           width is not limited, height must always be 8; if the text is
                larger than the control width, it will only be cut, if the
                "fill background" option is activated
Description:    Plots a text. If "fill background" is activated first the whole
                area of the control will be filled with the paper-colour.
-------------------------------------------------------------------------------
ID:             02 (PLR)
Name:           paint_frame
Parameter:      [bit0-1]=pen of upper and left line
                [bit2-3]=pen of lower and right line
                [bit4-5]=pen of area inside frame (only used, if bit6=1)
                [bit6]=if 1, fill area inside frame
Data record:    -
Size:           equal or greater than 3x3
Description:    Plots a frame. Optionally the area inside will be filled.
-------------------------------------------------------------------------------
ID:             03 (PLX)
Name:           paint_frame_with_title
Parameter:      pointer to data record
Data record:    00  1W  text address (terminated by 0)
                02  1B  [bit0-1]=paper, [bit2-3]=pen of text and line
Size:           equal or greater than 16x16
Description:    Plots a frame with a text title. Notice, that the lines have a
                distance of 3 pixels to the border of the control. The area
                inside the frame will not be filled.
-------------------------------------------------------------------------------
ID:             04 (PLP)
Name:           paint_progress
Parameter:      [bit0-1]=pen of upper and left line
                [bit2-3]=pen of lower and right line
                [bit4-5]=pen of filled area inside frame
                [bit6-7]=pen of empty area inside frame
                [bit8-15]=progress (0=0%, 255=100%)
Data record:    -
Size:           equal or greater than 3x3
Description:    Plots a progress bar. The second byte of the parameter
                specifies the progress in 1/255 steps.
-------------------------------------------------------------------------------

===============================================================================
GRAPHICS
-------------------------------------------------------------------------------
ID:             08 (ICN)
Name:           graphic_simple
Parameter:      grafic address
Data record:    -
Size:           same as the graphic object
Description:    Plots a graphic. For the description how a graphic object is
                stored in the memory see below (GRAPHICS). The control must
                have the same size like the graphic.
-------------------------------------------------------------------------------
ID:             09 (ICT)
Name:           graphic_with_text
Parameter:      pointer to data record
Data record:    00  1W  graphic address
                02  1W  0 or address of text for line 1 (terminated by 0)
                04  1W  0 or address of text for line 2 (terminated by 0)
                06  1B  [bit0-1]=paper, [bit2-3]=pen
Size:           48x40
Description:    Plots a graphic with one or two textlines below. It is used for
                displaying icons. When there is a 0 instead of a text address,
                the line will stay empty. The graphic itself must have a size
                of 24x24.
-------------------------------------------------------------------------------

===============================================================================
BUTTONS
-------------------------------------------------------------------------------
ID:             16 (BTN)
Name:           button_simple
Parameter:      text address (terminated by 0)
Data record:    -
Size:           width is not limited, height must always be 12
Description:    Plots a button with a centered text inside. Pen 2 is used for
                the background, pen 1 for text colour and right/lower lines,
                pen 3 for left/upper lines.
-------------------------------------------------------------------------------
ID:             17 (BTC)
Name:           button_check
Parameter:      pointer to data record
Data record:    00  1W  address of status byte (this byte can be 0 or 1)
                02  1W  text address (terminated by 0)
                04  1B  [bit0-1]=text paper, [bit2-3]=text pen
Size:           width is not limited, height must always be 8
Description:    Plots a check box followed by a textline. The status byte
                contains 1, if the box is checked, otherwise it contains 0.
-------------------------------------------------------------------------------
ID:             18 (BTR)
Name:           button_radio
Parameter:      pointer to data record
Data record:    00  1W  address of global status byte
                02  1W  text address (terminated by 0)
                04  1B  [bit0-1]=text paper, [bit2-3]=text pen
                05  1B  value of the own status
                06  1W  pointer a global 4byte coordinate buffer
Size:           width is not limited, height must always be 8
Description:    Plots a radio button followed by a textline. If the global
                status byte has the same value as the own status, this radio
                button is checked. The 4byte coordinate buffer has to contain
                -1,-1,-1,-1 at the beginning. It stores the coordinates of the
                actual checked radio button.
                Radio buttons, which are connected to each other, have to point
                to the same global status byte and the same coordinate buffer.
-------------------------------------------------------------------------------
ID:             19 (BTP)
Name:           button_hidden
Parameter:      -
Data record:    -
Size:           not limited
Description:    This just defines an area on which the user can click. Nothing
                will be displayed.
-------------------------------------------------------------------------------
ID:             20 (BTT)
Name:           button_tabs
Parameter:      pointer to data record
Data record:    00  1B  number of tabs
                01  1B  [bit0-1]=paper, [bit2-3]=pen,
                        [bit4-5]=colour of left/upper lines,
                        [bit6-7]=colour of right/lower lines
                02  1B  selected tab
                03  1W  text address of tab 1 title (terminated by 0)
                05  1B  -1 or width of tab 1 title
                06  1W  text address of tab 2 title (terminated by 0)
                08  1B  -1 or width of tab 2 title
                ...
                ??  1W text address of tab n title
                ??  1B -1 or width of tab n title
Size:           width is not limited, height must always be 11
Description:    Plots a tab line. If -1 is set as the width of one tab title
                the system will calculate the needed width by itself.
-------------------------------------------------------------------------------

===============================================================================
SLIDER
-------------------------------------------------------------------------------
ID:             24 (SLD)
Name:           slider_simple
Parameter:      pointer to data record
Data record:    00  1B  [bit0]=alignment (0=vertical, 1=horizontal)
                        [bit1]=type (0=value control, 1=window section control)
                01  1B  [*not used, set to 0*]
                02  1W  actual value/position
                04  1W  maximum value/position (range is 0 - maximum)
                06  1B  value increase, if the user clicks the down/left button
                07  1B  value decrease, if the user clicks the up/right button
Size:           depending on the alignment, one component is not limited; the
                other one must be always 8.
Description:    Plots a slider. It can be used to control a value or to move
                inside a window or list.
-------------------------------------------------------------------------------

===============================================================================
TEXTINPUT
-------------------------------------------------------------------------------
ID:             32 (TXL)
Name:           textinput_line
Parameter:      pointer to data record
Data record:    00  1W  address of text (has to be large enough, see below)
                02  1W  first displayed character
                04  1W  cursor position
                06  1W  number of selected characters (0=no selection, <0
                        cursor is placed at the end of the selection, >0 cursor
                        is placed at the beginning of the selection)
                08  1W  length of the current text
                10  1W  possible maximum text length (doesn't include the 0
                        terminator at the end of the text)
                12  1B  [bit0]=Flag, if Password (all chars will be displayed
                               as '*')
Size:           width is not limited, height must always be 12
Description:    -
-------------------------------------------------------------------------------
ID:             33 (TXB)
Name:           textinput_box
Parameter:      pointer to data record
Data record:    [...]
Description:    [not yet implemented]
-------------------------------------------------------------------------------

===============================================================================
LISTS
-------------------------------------------------------------------------------
ID:             40 (LST)
Name:           list_title
Parameter:      pointer to data record
Data record:    00  1W  number of lines
                02  1W  first displayed line of the list
                04  1W  pointer to data record for the list content
                06  2B  [*not used, set to 0*]
                08  1B  number of columns (1-64)
                09  1B  [bit0-5]=number of sorted column
                        [bit6]=sort list on start
                        [bit7]=sort order (0=ascending, 1=descending)
                10  1W  pointer to data record for the columns
                12  1W  last clicked line
                14  1B  [bit0]=flag, if list slider will be displayed
                        [bit1]=flag, if multiselections are possible
                15  1B  [*not used, set to 0*]
Column record:  [Number of columns] * [
                00  1B  [bit0-1]=allignment (0=left, 1=right, 2=center)
                        [bit2-3]=type (0=text, 1=graphic, 2=16bit number,
                                 3=32bit number)
                01  1B  [*not used, set to 0*]
                02  1W  width of this column in pixel
                04  1W  text address of the title (terminated by 0)
                06  2B  [*not used, set to 0*]
                ]
List record:    [Number of lines] * [
                    1W  [bit0-13]=value of this line
                        [bit14]=set to 0, it is used for "selection update"
                        [bit15]=flag, if this line is selected
                    [Number of columns] *
                        1W  text/data address or value for this cell
                ]
Size:           width is not limited, height must always be 10
Description:    Plots the title line of a list.
-------------------------------------------------------------------------------
ID:             41 (LSI)
Name:           list_content
Parameter:      pointer to data record
Data record:    [see ID 40]
Size:           width must be equal or larger than 11, height must be equal or
                larger than 16
Description:    Plots the list itself without the title.
-------------------------------------------------------------------------------
ID:             42 (LSP)
Name:           list_dropdown
Parameter:      pointer to data record
Data record:    [see ID 40]
                12  1W  last clicked line
                        -> this always represents the selected line!
                14  1B  [bit0]=flag, if list slider will be displayed
                        -> should be set to 1, if list has more than 10 entries
                        [bit1]=flag, if multiselections are possible
                        -> always set to 0!
Size:           width must be equal or larger than 11, height must always be 10
Description:    Plots a dropdown list. Only one line of the list will be
                displayed. If the user clicks on this control, the complete
                list will drop down and the user can choose one of the entries.
-------------------------------------------------------------------------------
ID:             43 (LSC)
Name:           list_complete
Parameter:      pointer to data record
Data record:    [see ID 40]
Size:           width must be equal or larger than 11, height must be equal or
                larger than 26
Description:    Plots the list title and the list itself together. This is the
                combination of ID 40 and ID 41.
-------------------------------------------------------------------------------



PULLDOWN MENUS

===============================================================================
MENU RECORD

You can define up to 8 sub menu levels. The WINDOW DATA RECORD points to the
highest menu level. These are the entries you see in the menu bar of a window.
These entries usually point to their sub menus, which contain entries, too,
which are clickable or which point to an additional sub menu again.
-------------------------------------------------------------------------------
00  1W  Number of entries
[Number of entries] * [
00  1W  [bit0]=flag, if the menu entry is active. Deactivated entries can't be
               clicked by the user and will appear in a different colour
        [bit1]=flag, if there is a check mark behind the entry
        [bit2]=flag, if the entry opens a sub menu
        [bit3]=flag, if there is no entry but a separator line
02  1W  text address (terminated by 0). If bit3 of the previous word is set,
        you can use 0 here
04  1W  Value, if the entry is clickable, or address of the sub menu data
        record, if bit2 of the first word is set.
06  1W  [*reserved, set to 0*]
]
-------------------------------------------------------------------------------



GRAPHICS

===============================================================================
Each SymbOS graphic object starts with a 3 byte header:
00  1B  Width of the graphic in bytes
01  1B  Width of the graphic in pixel
02  1B  Height of the graphic in pixel
Directly behind the header the amount of [Width_in_bytes] * [Height_in_pixel]
bytes is following containing the graphic data. Every graphic is stored line by
line like a sprite.

The pixels are coded in CPC Mode 1 format, evey byte contains 4 pixels:
bit7 = bit0 of pixel0 (left pixel)
bit6 = bit0 of pixel1
bit5 = bit0 of pixel2
bit4 = bit0 of pixel3 (right pixel)
bit3 = bit1 of pixel0
bit2 = bit1 of pixel1
bit1 = bit1 of pixel2
bit0 = bit1 of pixel3

Or you can see it like this:
pixel0 = bit7 + 2 * bit3 (left pixel)
pixel1 = bit6 + 2 * bit2
pixel2 = bit5 + 2 * bit1
pixel3 = bit4 + 2 * bit0 (right pixel)
