[Contents] [index] [Help] [Retrace] [browse <] [Browse >]

The sections above discuss only the basic functions and screen types that
Intuition programmers need to understand to create a custom screen.
Intuition supports an astonishing number of additional display features
and options.  In this section and the sections to follow, the finer points
of screen attributes and the functions that control them are presented.

Screen attributes are specified using the tag item scheme described in the
"utility library" chapter.  therefore, the screen attributes are listed
here by tag values.  (In V34, the newscreen structure was used to set
screen attributes so many of the tag options listed here have a
corresponding flag in NewScreen.)  In general, specifying a tag overrides
the corresponding flag or field in the NewScreen structure if you supply
one.

SA_ErrorCode
    Extended error code.  Data is a pointer to a long which will contain
    the error code on return if openscreentaglist() returns null. the
    error codes are described above.

SA_Left, SA_Top
    Initial screen position (left edge and top edge).  Data is a long,
    signed value.  Offsets are relative to the text overscan rectangle.

    If SA_Left is not specified and a newscreen structure is not passed
    in the openscreentags/taglist() call and sa_width is not specified
    or is specified as STDSCREENWIDTH, then the left edge of the screen
    will default to the left edge of the actual display clip of the
    screen.  If the other conditions are met but some explicit SA_Width
    is specified, then the left edge defaults to zero (text overscan
    rectangle left edge).  Likewise, the top edge may, independent of the
    left edge value, default to zero or to the top edge of the actual
    display clip.  If SA_Top is not specified and a NewScreen structure
    is not passed in the OpenScreenTags/TagList() call and SA_Height is
    not specified or specified as STDSCREENHEIGHT, then the top edge of
    the screen will default to the top edge of the actual display clip of
    the screen.  If the other conditions are met but some explicit
    SA_Height is specified, then the top edge defaults to zero (text
    overscan rectangle top edge).  Prior to V36, left edge positioning is
    ignored and negative top edge positions are illegal.

    When opening a full sized overscan screen, SA_Left should be set to
    the MinX value of the display clip rectangle used for the screen and
    SA_Top should be set to the MinY value of the display clip.  This may
    be taken from the defaults, as explained above, or explicitly set by
    the application.  See the section below "overscan and the display clip"
    and the openscreen() autodoc for more details.

    If your screen is larger than your display clip, you may wish to set
    the SA_Left and SA_Top to values less than your display clip MinX and
    MinY in order to center a large screen on a smaller display.  For an
    example of how to open a centered overscan screen, see
    module/screen.c in the iff appendix of the amiga rom kernel reference
    Manual: Devices.

SA_Width, SA_Height
    Screen dimensions.  Data is a long, unsigned value.  These may be
    larger, smaller or the same as the dimensions of the display clip
    rectangle.  the use of stdscreenwidth and stdscreenheight will make
    the screen size equal to the display clip size.

    To calculate the width of the display clip rectangle, subtract the
    MinX value from the MaxX value plus one.  Similarly, the height of
    the display clip may be calculated by subtracting the MinY value from
    the MaxY value plus one.

SA_Depth
    Screen bitmap depth.  Data is a long, unsigned value.  The depth of
    the screen determines the number of available colors.  See the
    "graphics primitives" for more information on hardware limitations of
    the display.  Do not set the depth to a value greater than that
    supported by the specific display mode.  This information is
    available to the application through the graphics library display
    database.  The default is one bitplane.

SA_DisplayID
    Extended display mode key for the screen.  Data is a long, unsigned
    value.  By using Release 2 DisplayIDs and the display database,
    applications can open a screen in any display mode available on a
    user's system, including PAL and NTSC modes.  See the discussion of
    the display database in the "graphics primitives" chapter and the
    include file <graphics/displayinfo.h> for more information.

SA_Pens
    Pen specification for the screen.  Data is a pointer to a UWORD array
    terminated with ~0, as found in the drawinfo structure.  specifying
    the SA_Pens tag informs the system that the application is prepared
    to handle a screen rendered with the new 3D look of Intuition.  See
    the section below on "drawinfo and the 3d look". omitting this tag
    produces a screen with a flat look, but whose color usage is more
    backwards compatible.

SA_DetailPen
    Detail pen for the screen.  Data is a long, unsigned value.  Used for
    rendering details in the screen title bar and menus.  Use SA_Pens
    beginning with V36 for more control of pen specification.  If SA_Pens
    is not specified, the screen will not get the new 3D look of
    Intuition available in Release 2.  Instead this value will be used as
    the detail pen.

SA_BlockPen
    Block pen for the screen.  Data is a long, unsigned value.  Used for
    rendering block fills in the screen title bar and menus.  Use SA_Pens
    beginning with V36 for more control of pen specification.  If SA_Pens
    is not specified, the screen will not get the new 3D look and this
    value will be used as the block pen.

SA_Title
    Default screen title.  Data is a pointer to a character string.  This
    is the title displayed when the active window has no screen title or
    when no window is active on the screen.

SA_Colors
    Specifies initial screen palette colors.  Data is a pointer to an
    array of colorspec structures, terminated by a colorspec structure
    with ColorIndex=-1. Screen colors may be changed after the screen is
    opened with the graphics library functions setrgb4() and loadrgb4().
    ColorSpec colors are right-justified, four bits per gun.

SA_FullPalette
    Initialize color table to entire preferences palette (32 colors
    beginning with V36), rather than the subset from V34 and earlier,
    namely pens 0-3, 17-19, with remaining palette as returned by
    getcolormap().  data is a boolean value (use true to set the flag).
    Defaults to FALSE.

SA_Font
    Data is a pointer to a textattr structure (defined in
    <graphics/text.h> ) which specifies the font, size and style to use
    for the screen.  Equivalent to newscreen.font.

SA_SysFont
    Alternative to SA_Font.  Selects one of the preferences system fonts.
    Data is a long, unsigned value, with the following values defined:

        0  Open screen with the user's preferred fixed width font
           (the default).
        1  Open screen with the user's preferred font, which may be
           proportional.

    The Workbench screen is opened with {SA_SysFont , 1}.  Table 3-4
    summarizes how the font selected at openscreen() time effects
    subsequent text operations in screens and windows.


                Table 3-4: Intuition Font Selection Chart

       What you tell
       openscreen()            screen font            window.rport font
       -------------           -----------            -----------------
    A. newscreen.font=myfont  myfont                  myfont
    B. NewScreen.Font=NULL    GfxBase->DefaultFont    GfxBase->DefaultFont
    C. {SA_Font, myfont}      myfont                  myfont
    D. {SA_SysFont, 0}        GfxBase->DefaultFont    GfxBase->DefaultFont
    E. {SA_SysFont, 1}        Font Prefs Screen text  GfxBase->DefaultFont

       Notes:
     * A and B are the options that existed in V34 and earlier OS versions.
     * C and D are tags in Release 2 equivalent to A and B respectively.
     * E is a new option for V36.  The Workbench screen uses this option.
     * For `myfont', any font may be used including a proportional one.
       This is true under all releases of the OS.
     * GfxBase->DefaultFont is always monospace.  (This is the "System
       Default Text" from Font Preferences.)
     * Font Prefs Screen text (the "Screen Text" choice from Font
       Preferences) can be monospace or proportional.


    The screen's font may not legally be changed after a screen is
    opened. The menu bar, window titles, menu items, and the contents of
    a string gadget all use the screen's font.  The font used for menu
    items can be overridden in the menu item's intuitext structure.
    Under V36 and higher, the font used in a string gadget can be
    overridden through the stringextend structure.  the font of the menu
    bar and window titles cannot be overridden.

    The window.rport font shown above is the initial font that intuition
    sets in your window's rastport.  it is legal to change that
    subsequently with setfont().  intuitext rendered into a window
    (either through printitext() or as a gadget's gadgettext) defaults to
    the window's RastPort font, but can be overridden using its itextfont
    field.  Text rendered with the graphics library call text() uses the
    window's RastPort font.

SA_Type
    Equivalent to the SCREENTYPE bits of the newscreen.type field.  data
    is a long, unsigned value which may be set to either CUSTOMSCREEN or
    PUBLICSCREEN (WBENCHSCREEN is reserved for system use).  See the tags
    SA_BitMap, SA_Behind, SA_Quiet, SA_ShowTitle and SA_AutoScroll for
    the other attributes of the NewScreen.Type field.

SA_BitMap
    Use a custom bitmap for this screen.  Data is a pointer to a bitmap
    structure.  This tag is equivalent to newscreen.custombitmap and
    implies the CUSTOMBITMAP flag of the NewScreen.Type field.  The
    application is responsible for allocating and freeing the screen's
    bitmap.

SA_Behind
    Open this screen behind all other screens in the system.  Data is a
    boolean value (TRUE to set flag).  This tag is equivalent to the
    SCREENBEHIND flag of the newscreen.type field.

SA_Quiet
    Disable Intuition rendering into screen.  Data is a boolean value
    (TRUE to set flag).  This tag is equivalent to the SCREENQUIET flag
    of the newscreen.type field.  the screen will have no visible title
    bar or gadgets, but dragging and depth arrangement still function.
    In order to completely prevent Intuition from rendering into the
    screen, menu operations must be disabled for each window in the
    screen using WFLG_RMBTRAP.

SA_ShowTitle
    Setting this flag places the screen's title bar in front of any
    backdrop windows that are opened on the screen.  Data is a boolean
    value (TRUE to set flag).  This tag is equivalent to the SHOWTITLE
    flag of the newscreen.type field.  the title bar of the screen is
    always displayed behind any non-backdrop windows on that screen.
    This attribute can be changed after the screen is open with the
    showtitle() function.

SA_AutoScroll
    Setting this flag will enable autoscroll for this screen when it is
    the active screen.  (Currently, the screen may only be made active by
    activating a window in that screen either under user or application
    control.)  Data is a boolean value (TRUE to set flag).  This tag is
    equivalent to the AUTOSCROLL flag of the newscreen.type field.

    Autoscroll means that screens larger than the visible display will
    automatically scroll when the user moves the mouse to the edge of the
    screen.  Without this tag, the user moves the screen either by using
    the screen drag bar, or by pressing the mouse select button anywhere
    within the screen while holding down the left Amiga key and moving
    the mouse.

SA_PubName
    Presence of this tag means that the screen is to be a public screen.
    Data is a pointer to a string.  The string is the name of the public
    screen which is used by other applications to find the screen.  This
    tag is order dependent, specify before SA_PubSig and SA_PubTask.

SA_PubSig, SA_PubTask
    Task ID (returned by findtask()) and signal for notification that the
    last window has closed on a public screen. data for sa_pubsig is a
    long, unsigned value. Data for SA_PubTask is a pointer to a task
    structure. These two tags are order dependent, and must be specified
    after the tag SA_PubName.

SA_Overscan
    Set to one of the OSCAN_ specifiers to use a system standard overscan
    display clip and screen dimensions (unless otherwise specified).
    Data is a long, unsigned value.  Do not specify this tag and
    SA_DClip.  SA_Overscan is used to get one of the standard overscan
    dimensions, while SA_DClip is for custom dimensions.  If a display
    clip is not specified with either SA_Overscan or SA_DClip, the
    display clip defaults to oscan_text.  see the section below on
    "overscan and the display clip" for more information.

SA_DClip
    Custom display clip specification.  Data is a pointer to a rectangle
    structure that defines the screen display clip region.