home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / datafiles / text / c_manual / intuition / screens / screens.doc < prev    next >
Text File  |  1995-02-27  |  20KB  |  618 lines
  1. 1    SCREENS
  2.  
  3. 1.1  INTRODUCTION
  4.  
  5. The screen is the foundation of Intuition's display. It
  6. determines how many colours you can use, what kind of colours,
  7. what resolution etc. Every window, gadget, icon, drawing is
  8. connected to a screen. Moving that screen, and you are also
  9. moving the objects on it. You may have several screens running
  10. at the same time, and you may combine different screens (with
  11. their own individual resolutions, colours, etc) on the same
  12. display.
  13.  
  14. In this chapter we will only look at the "standard screens"
  15. which all Amiga models support. There exist new models like
  16. the Amiga 3000 which can use new types screens with different
  17. sizes and limitations. Since only some models support these
  18. new modes there will be a special chapter about this.
  19.  
  20. What is described in the following chapters will work on all
  21. Amiga models.
  22.  
  23.  
  24.  
  25. 1.2  DIFFERENT TYPES OF SCREENS
  26.  
  27. When you are going to use a screen you first need to decide if
  28. you want to use a Standard (Workbench) Screen or if you want to
  29. use a Screen which you yourself have customized (Custom Screens).
  30.  
  31. Workbench Screen:
  32.   This is Intuition's standard screen. It is a four-colour,
  33.   high-resolution screen. 
  34.  
  35. Custom Screens:
  36.   When you want a screen with your own display mode you should
  37.   use a Custom Screen. You can then decide yourself how many
  38.   colours you want, what colours, resolution, size etc.
  39.  
  40. If your program should use a high-resolution screen, and four
  41. colours is enough, you are advised to use the Workbench Screen.
  42. This will save a lot of memory (no memory allocated for a
  43. Custom Screen), and allows the user to have several programs
  44. running on the same display. On the other hand, if you want
  45. more colours or want to use a different resolution/display-mode
  46. you should use a Custom Screen.
  47.  
  48.  
  49.  
  50. 1.3  WORKBENCH SCREEN
  51.  
  52. Workbench Screen is a high-resolution (640 pixels wide), four
  53. colour screen. It is either 200 or 256 lines high depending on
  54. if you have a NTSC (American) or a PAL (European) computer.
  55. (400/512 lines if you have an Interlaced display.)
  56.  
  57. The Workbench Screen will automatically open if there does not
  58. exist any other screens. If you do not want the Workbench
  59. Screen, and need a lot of memory, you can try to close it,
  60. CloseWorkBench(). Remember to reopen it when your program has
  61. finished, OpenWorkBench().
  62.  
  63. You are advised to always call the function OpenWorkBench()
  64. when your program exits, even if you have not closed it
  65. yourself. Another program may have closed it because of
  66. shortage of memory, and when your program is finished there
  67. may exist enough memory. This will make the Workbench Screen
  68. available as much as possible.
  69.  
  70.  
  71.  
  72. 1.4  CUSTOM SCREENS
  73.  
  74. If you are going to use a Custom Screen you need to initialize
  75. a structure (NewScreen) with your requirements. You also need
  76. to open the screen yourself by calling the function
  77. OpenScreen().
  78.  
  79. Here is a list of some important decisions you need to make
  80. before you can open the screen:
  81.  
  82.  
  83.   
  84. 1.4.1  RESOLUTION
  85.  
  86. You can either have a high-resolution or a low-resolution
  87. screen. A high resolution screen is 640 pixels wide, while a
  88. low-resolution screen is only 320 pixels wide. However, a high-
  89. resolution screen may only have a depth of up to 4 (maximum 16
  90. colours), while a low-resolution screen may have a depth of up
  91. to 5 (32 colours), or even 6 if using some special display
  92. modes.
  93.  
  94.  
  95.  
  96. 1.4.2  DEPTH
  97.  
  98. A screen's depth means how many bits are used for every pixel.
  99. The more bits the more combinations/colours:
  100.  
  101. Depth   Number of colours   Colour register number
  102. --------------------------------------------------
  103.   1             2                   0 -  1
  104.   2             4                   0 -  3
  105.   3             8                   0 -  7
  106.   4            16                   0 - 15
  107.   5            32                   0 - 31  (Only low-res)
  108.  
  109. A low resolution screen may even have a depth of 6 if using
  110. some special display modes (HAM / EXTRA HALFBRIGHTE ).
  111.  
  112. Each colour may be picked out of a 4096 colour palette. Once
  113. you have opened your Custom Screen you may change the colours
  114. by calling the graphics function SetRGB4().
  115.  
  116.  
  117.  
  118. 1.4.3  INTERLACED
  119.  
  120. An Interlaced screen can be 400/512 lines while a Non-
  121. Interlaced screen can only be 200/256 lines. You are recommended
  122. to use a Non-Interlaced screen if possible, since an Interlaced
  123. display appear to "flicker" if the user does not have a special
  124. high-phosphor-persistence monitor. (99% of the users do not
  125. have it.)
  126.  
  127. The monitor normally draws the display 50 times per second. If
  128. you are using an Interlaced screen the Amiga will only draw
  129. every second line first, and will the next time draw the
  130. remaining lines. This is why an Interlaced display appear to
  131. "flicker". You can eliminate much of the disturbing effects if
  132. you are using colours with low contrasts, black and grey
  133. instead of black and white for example.
  134.  
  135.  
  136.  
  137. 1.4.4  HAM AND EXTRA HALFBRIGHTE
  138.  
  139. If you have a low-resolution, six bitplanes (Depth 6) screen
  140. you can either use the special HAM mode, or the Extra
  141. Halfbrighte mode. HAM allows you to display all 4096 colours
  142. at the same time, but has some restrictions, and is
  143. complicated to use. Extra Halfbrighte gives you 32 extra
  144. colours, which are the same as the first 32 colours, but are
  145. a bit brighter.
  146.  
  147. Both HAM and Extra Halfbrighte is using a lot of memory/
  148. processing time, and is therefore not commonly used.
  149.  
  150.  
  151.  
  152. 1.4.5  DUAL PLAYFIELDS
  153.  
  154. Dual Playfields allows you to have two screens on top of each
  155. other. The top screen can then be transparent in some places
  156. (colour register 0) to show the bottom screen.
  157.  
  158.  
  159.  
  160. 1.4.6  FONTS
  161.  
  162. You can specify a default font which will be used, if nothing
  163. else is specified, to draw the text on the screen. The system's
  164. default font is called Topaz and exist in two sizes:
  165.  
  166. TOPAZ_SIXTY  : 9 lines tall, 64/32 characters per line.
  167. TOPAZ_EIGHTY : 8 lines tall, 80/40 characters per line.
  168.  
  169. This font is built in the Amiga, and is therefore always
  170. available. (See chapter 3 GRAPHICS for more information.)
  171.  
  172.  
  173.  
  174. 1.4.7  SIZE AND POSITION
  175.  
  176. The top of your screen does not need to be at the top of the
  177. display. You may open several screens and position them under
  178. each other. If you are, for example, designing an adventure
  179. game, you can have a low-resolution 32 colour screen at the top
  180. of the display (showing some nice pictures), and have a high-
  181. resolution 2 colour screen at the bottom of the display (showing
  182. the text).
  183.  
  184. (Remember that the user later can drag the screens up or down
  185. himself.) 
  186.  
  187. The width of the screen should be either 320 (low-resolution)
  188. or 640 pixels (high-resolution).
  189.  
  190. The height may be anything between 1 - 200/256 lines on an Non-
  191. Interlaced screen, and between 1 - 400/512 lines on an
  192. Interlaced display.
  193.  
  194.  
  195.  
  196. 1.4.8  TITLE
  197.  
  198. On top of each screen (on the "drag bar") there exist a screen
  199. title. There exist two kinds of titles:
  200.   - The default title, which is specified in the NewScreen
  201.     structure.
  202.   - A "current" title which is the same as the title of the
  203.     current active window. (See chapter 2 WINDOWS for more
  204.     information.)
  205.  
  206.  
  207.  
  208. 1.4.9  GADGETS
  209.  
  210. For the moment you are not allowed to attach any custom gadgets
  211. to a screen. (See chapter 4 GADGETS for more information about
  212. gadgets.)
  213.  
  214.  
  215.  
  216. 1.5  INITIALIZE A CUSTOM SCREEN
  217.  
  218. Before you can open a custom screen you need to initialize a
  219. NewScreen structure which look like this:
  220.  
  221. struct NewScreen
  222. {
  223.   SHORT LeftEdge, TopEdge, Width, Height, Depth;
  224.   UBYTE DetailPen, BlockPen;
  225.   USHORT ViewModes;
  226.   USHORT Type;
  227.   struct TextAttr *Font;
  228.   UBYTE *DefaultTitle;
  229.   struct Gadget *Gadgets;
  230.   struct BitMap *CustomBitMap;
  231. };
  232.  
  233. LeftEdge:     Initial x position of the screen. Should always
  234.               be 0.
  235.  
  236. TopEdge:      Initial y position of the screen.
  237.  
  238. Width:        If it is a low-resolution screen it should be
  239.               320, otherwise 640.
  240.  
  241. Height:       If it is a Non-Interlaced screen it can be
  242.               anything between 1 - 200/256, otherwise 1 -
  243.               400/512.
  244.  
  245. Depth:        1-4 if high-resolution, otherwise 1-6.
  246.  
  247. DetailPen:    The colour register used to draw the text with.
  248.  
  249. BlockPen:     The colour register used for block fills etc.
  250.  
  251. ViewModes:    You can use none or some of the flags. If you set
  252.               more than one flag you put a "|" between them.
  253.               (You are not allowed to set the HIRES flag
  254.               together with the DUALPF or HAM flag, and you
  255.               can not have DUALPF at the same time as HAM.)
  256.  
  257.                 HIRES      Set this flag if you want a high-
  258.                            resolution screen. (The default is
  259.                            low-resolution.)
  260.  
  261.                 INTERLACE  Set this flag if you want an
  262.                            Interlaced screen. (The default
  263.                            is Non-Interlaced)
  264.  
  265.                 SPRITES    Set this flag if you are going to
  266.                            use sprites in your display.
  267.  
  268.                 DUALPF     Set this flag if you want to use the
  269.                            Dual Playfields Mode.
  270.  
  271.                 HAM        Set this flag if you want to use the
  272.                            Hold And Modify Mode.
  273.  
  274. Type:         Should be CUSTOMSCREEN. You can also set the
  275.               CUSTOMBITMAP flag if you want the screen to use
  276.               your own declared and initialized BitMap. (See
  277.               chapter 2 WINDOWS for more information about
  278.               Custom BitMaps.)
  279.  
  280. Font:         A pointer to an already initialized TextAttr
  281.               structure. The screen will use it as the default
  282.               font. (See chapter 3 GRAPHICS for more information
  283.               about fonts.) Set to NULL if you want to use the
  284.               current default font.
  285.  
  286. DefaultTitle: A pointer to a text string which will be used as
  287.               "default" title.
  288.  
  289. Gadgets:      Not used for the moment. Set to NULL.
  290.  
  291. CustomBitMap: If you want to use your own BitMap you should
  292.               give this field a pointer to the BitMap structure
  293.               which you have declared, and initialized yourself.
  294.               Remember to set the CUSTOMBITMAP flag in the Type
  295.               variable. However, if you want Intuition to take
  296.               care of the BitMap, set this field to NULL. (See
  297.               chapter 2 WINDOWS for more information about
  298.               Custom BitMaps.)
  299.  
  300.  
  301.  
  302. 1.6  OPEN A CUSTOM SCREEN
  303.  
  304. Once you have declared and initialized the NewScreen structure,
  305. you can call the function OpenScreen() which will open your
  306. Custom Screen. When your screen has been opened you can, if you
  307. have allocated memory for the NewScreen structure, deallocate
  308. it since you do not need the structure any more.
  309.  
  310. This is how you call the OpenScreen() function:
  311.  
  312. my_screen = OpenScreen( &my_new_screen ); 
  313.  
  314. my_screen has been declared as:
  315.   struct Screen *my_screen;
  316.  
  317. my_new_screen has been declared as:
  318.   struct NewScreen my_new_screen;
  319.   and has been initialized with your requirements.
  320.  
  321.  
  322. OpenScreen() will return a pointer to a Screen structure, else
  323. NULL if it could not open the screen (for example, not enough
  324. memory). Remember to check what OpenScreen() returned!
  325.  
  326. if( my_screen==NULL )
  327. {
  328.   /* PANIC! Could not open the screen */
  329. }
  330.  
  331.  
  332.  
  333. 1.7  SCREEN STRUCTURE
  334.  
  335. Once you have opened the screen you will receive a pointer to
  336. a Screen structure which look like this:
  337.  
  338. struct Screen
  339. {
  340.   struct Screen *NextScreen;    /* Pointer to the next */
  341.                                 /* screen, or NULL. */
  342.   struct Window *FirstWindow;   /* Pointer to the first */
  343.                                 /* Window on this screen. */
  344.   SHORT LeftEdge, TopEdge;      /* Position of the screen. */
  345.   SHORT Width, Height;          /* Size of the screen. */
  346.   SHORT MouseY, MouseX;         /* Mouse position relative */
  347.                                 /* to the top left corner */
  348.                                 /* of the screen. */
  349.   USHORT Flags;                 /* The selected flags. */
  350.   UBYTE *Title;                 /* The screen's Current title. */
  351.   UBYTE *DefaultTitle;          /* The screen's Default title. */
  352.  
  353.   BYTE BarHeight, BarVBorder,
  354.        BarHBorder, MenuVBorder,
  355.        MenuHBorder;
  356.   BYTE WBorTop, WBorLeft,
  357.        WBorRight, WBorBottom;
  358.  
  359.   struct TextAttr *Font;        /* The screens default font. */
  360.   struct ViewPort ViewPort;     /* The screen's ViewPort etc: */
  361.   struct RastPort RastPort;
  362.   struct BitMap BitMap;
  363.   struct Layer_Info LayerInfo;
  364.   struct Gadget *FirstGadget;
  365.   UBYTE DetailPen, BlockPen;
  366.   USHORT SaveColor0;
  367.   struct Layer *BarLayer;
  368.   UBYTE *ExtData;
  369.   UBYTE *UserData;
  370. };
  371.  
  372. You will probably not use this structure a lot, but some
  373. variables/structures can be useful later on. When you are, for
  374. example, using the function SetRGB4(). More about this later.
  375.  
  376.  
  377.  
  378. 1.8  FUNCTIONS
  379.  
  380. Here are some common functions which will affect screens:
  381.  
  382. OpenScreen()
  383.  
  384.   This function will open a Custom Screen with your
  385.   requirements.
  386.  
  387.   Synopsis:      my_screen = OpenScreen( my_new_screen );
  388.   
  389.   my_screen:     (struct Screen *) Pointer to a Screen
  390.                  structure. It will point to your newly opened
  391.                  screen or be equal to NULL if the screen could
  392.                  not be opened.
  393.  
  394.   my_new_screen: (struct NewScreen *) Pointer to a NewScreen
  395.                  structure which contains your preferences.
  396.  
  397.  
  398. CloseScreen()
  399.  
  400.   This function will close a Custom Screen which you have
  401.   previously opened.
  402.   
  403.   Synopsis:      CloseScreen( my_screen );
  404.   
  405.   my_screen:     (struct Screen *) Pointer to an already opened
  406.                  screen.
  407.  
  408.   All windows (See chapter 2 WINDOWS for more information) on
  409.   your Screen MUST have been closed before you may close the
  410.   screen. If you close a window after the screen has been
  411.   closed, the system will crash. (Not recommended.)
  412.   
  413.   If there does not exist any more screens when you close
  414.   yours, Intuition will automatically reopen the Workbench
  415.   Screen.
  416.  
  417.  
  418. MoveScreen()
  419.  
  420.   This function will move the screen. For the moment you may
  421.   only move it vertically.
  422.  
  423.   Synopsis:      MoveScreen( my_screen, delta_x, delta_y );
  424.  
  425.   my_screen:     (struct Screen *) Pointer to the screen which
  426.                  you want to move.
  427.  
  428.   delta_x:       (long) Number of pixels which the screen
  429.                  should move horizontally. For the moment you
  430.                  may not move a screen horizontally, set it
  431.                  therefore to 0.
  432.  
  433.   delta_y:       (long) Number of lines which the screen should
  434.                  move vertically.
  435.  
  436.  
  437. ScreenToBack()
  438.  
  439.   This will move the screen behind all other screens.
  440.   
  441.   Synopsis:      ScreenToBack( my_screen );
  442.  
  443.   my_screen:     (struct Screen *) Pointer to the screen which
  444.                  you want to move.
  445.  
  446.  
  447. ScreenToFront()
  448.  
  449.   This will move the screen in front of all other screens.
  450.   
  451.   Synopsis:      ScreenToFront( my_screen );
  452.  
  453.   my_screen:     (struct Screen *) Pointer to the screen which
  454.                  you want to move.
  455.  
  456.  
  457. ShowTitle()
  458.  
  459.   This function will make the screen's Title appear above or
  460.   behind any Backdrop Windows (See chapter 2 WINDOWS for more
  461.   information about Backdrop Windows). (The screen's title
  462.   appear always behind normal windows.)
  463.  
  464.   Synopsis:      ShowTitle( my_screen, show_it );
  465.  
  466.   my_screen:     (struct Screen *) Pointer to the screen.
  467.  
  468.   show_it:       (long) A boolean value which can be:
  469.                  TRUE:  The title will be in front of any
  470.                         Backdrop Windows, but behind any
  471.                         other windows.
  472.                  FALSE: The Title will be behind any windows.
  473.  
  474.  
  475. OpenWorkBench()
  476.  
  477.   This function will try to open the Workbench Screen if there
  478.   exist enough memory.
  479.   
  480.   Synopsis:      result = OpenWorkBench();
  481.   
  482.   result:        (long) A boolean value which tell us if the
  483.                  Workbench Screen has been (or already was)
  484.                  opened (TRUE), or not (FALSE).
  485.  
  486.  
  487. CloseWorkBench()
  488.  
  489.   This function will try to close the Workbench Screen if
  490.   possible. If any other programs is using the Workbench
  491.   Screen, the function can not close it. Closing the Workbench
  492.   will free some memory, and can therefore be used if your
  493.   program needs more memory.
  494.   
  495.   (Remember to reopen the Workbench Screen when your program
  496.   terminates.)
  497.  
  498.   Synopsis:      result = CloseWorkBench();
  499.   
  500.   result:        (long) A boolean value which tell us if the
  501.                  Workbench screen has been (or already was)
  502.                  closed (TRUE), or not (FALSE).
  503.  
  504.  
  505. WBenchToBack()
  506.  
  507.   This will move the Workbench Screen behind all other screens.
  508.   
  509.   Synopsis:      result = WBenchToBack();
  510.  
  511.   result:        (long) A boolean value which is TRUE if the
  512.                  Workbench screen was open, or FALSE it it was
  513.                  not.
  514.  
  515.  
  516. WBenchToFront()
  517.  
  518.   This will move the Workbench Screen in front of all other
  519.   screens.
  520.  
  521.   Synopsis:      result = WBenchToFront();
  522.  
  523.   result:        (long) A boolean value which is TRUE if the
  524.                  Workbench screen was open, or FALSE it it was
  525.                  not.
  526.  
  527.  
  528. SetRGB4()
  529.  
  530.   This function allows you to change your screen's colours.
  531.   Each colour may be picked out of a 4096 colour palette. (16
  532.   levels of red, 16 levels of green and 16 levels of blue;
  533.   16*16*16 = 4096.)
  534.  
  535.   IMPORTANT! Before you may use this function you must have
  536.   opened the Graphics Library. (All other functions are in the
  537.   Intuition Library.) (See chapter 0 INTRODUCTION for more
  538.   information.)
  539.  
  540.   Synopsis:   SetRGB4( viewport, register, red, green, blue );
  541.            
  542.   viewport:   (struct ViewPort *) Pointer to a ViewPort which
  543.               colour registers we are going to change. We can
  544.               find the screen's ViewPort in the Screen
  545.               structure. (If my_screen is a pointer to a Screen
  546.               structure, this will get us a pointer to that
  547.               screen's ViewPort: &my_screen->ViewPort)
  548.  
  549.   register:   (long) The colour register you want to change.
  550.               The screen's Depth decides how many colour
  551.               registers the screen have:
  552.  
  553.               Depth  Colour Registers
  554.               -----------------------
  555.               1      0 - 1
  556.               2      0 - 3
  557.               3      0 - 7
  558.               4      0 - 15
  559.               5      0 - 31
  560.               6      0 - 63
  561.  
  562.   red:        Amount of red. (0 - 15)
  563.  
  564.   green:      Amount of green. (0 - 15 )
  565.  
  566.   blue:       Amount of blue. (0 - 15 )
  567.  
  568.   Eg: SetRGB4( &my_screen->ViewPort, 2, 15, 15, 0 ); will
  569.   change colour register 2 to be light yellow. (Red and green
  570.   together will be yellow.)
  571.  
  572.  
  573.  
  574. 1.9  EXAMPLES
  575.  
  576. We have now talked about different screens, Workbench Screen
  577. and your own Custom Screens. We have looked at how you can
  578. change the Custom Screen's display mode, resolution, depth etc,
  579. and we have described some important functions. It is now time
  580. for us to have some examples to clear up any confusions.
  581.  
  582. All Examples, both the programs as well as the source codes,
  583. are in the same directory as this document.
  584.  
  585. Example 1
  586.   This program will open a low-resolution, non-Interlaced,
  587.   eight colour Custom Screen. It will display it for 30
  588.   seconds, and then close it.
  589.  
  590. Example 2
  591.   Same as Example 1 except that the screen will be a high-
  592.   resolution, Interlaced, 4 colour Custom Screen.
  593.  
  594. Example 3
  595.   Same as Example 1 except that we will use the TOPAZ_SIXTY
  596.   Italic style as default font. (See chapter 3 GRAPHICS for
  597.   more information about text styles.)
  598.  
  599. Example 4
  600.   This program will open two screens, one (low-resolution 32
  601.   colours) at the top of the display, and one (high-resolution
  602.   16 colours) a bit down.
  603.  
  604. Example 5
  605.   Same as Example 4 except that after 10 seconds the low-
  606.   resolution screen will move down 75 lines. After another 10
  607.   seconds it will be put in front of all other screens. 10
  608.   seconds later it will move down another 75 lines. The program
  609.   will wait 10 seconds before the screens are closed and the
  610.   program exits.
  611.  
  612. Example 6
  613.   This program will open a low-resolution, non-Interlaced, 4
  614.   colour Custom Screen. It will after 5 seconds start to change
  615.   the screens colours, and will after a while close the screen
  616.   and exit.
  617.  
  618.