home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / 3_1DOCS.DMS / in.adf / tutorials.lha / tutorials / V38_ASL < prev    next >
Encoding:
Text File  |  1993-11-04  |  15.6 KB  |  424 lines
  1.  
  2. The ASL Library and 2.1
  3. =======================
  4.  
  5. (c) Copyright 1992-93 Commodore-Amiga, Inc.  All Rights Reserved
  6.  
  7. Among the many improvements to the 2.1 version of the operating system,
  8. the ASL library now has a new type of requester: the screen mode
  9. requester.  There are also many new tags and new header files.  The
  10. purpose of this article is to summarize the changes in the 2.1 version of
  11. the ASL library. 
  12.  
  13.  
  14. The Screen Mode Requester
  15. =========================
  16.  
  17. The Screeen Mode requester provides application writers with a convenient
  18. way to ask the user for their screen display preferences.  You create an
  19. ASL screen mode requester the same way you create an ASL file requester or
  20. font requester; only the tags and structures used are different. 
  21.  
  22. There are three main functions to call:
  23.  
  24. · AllocAslRequest()     Sets up the ScreenModeRequester structure you need. 
  25.  
  26. · AslRequest()          Displays the requester you have set up with
  27.             AllocAslRequest(). 
  28.  
  29. · FreeAslRequest()      Frees the ScreenModeRequester structure and
  30.             other resources.
  31.  
  32. The first step is to set up a ScreenModeRequester structure with the
  33. AllocAslRequest() function.  The ScreenModeRequester structure is defined
  34. in <libraries/asl.h> as follows:
  35.  
  36.  struct ScreenModeRequester {
  37.      ULONG sm_DisplayID;            /* Display mode ID                  */
  38.      ULONG sm_DisplayWidth;         /* Width of display in pixels       */
  39.      ULONG sm_DisplayHeight;        /* Height of display in pixels      */
  40.      UWORD sm_DisplayDepth;         /* Number of bit-planes of display  */
  41.      UWORD sm_OverscanType;         /* Type of overscan of display      */
  42.      BOOL  sm_AutoScroll;           /* Display should auto-scroll?      */
  43.      ULONG sm_BitMapWidth;          /* Used to create your own BitMap   */
  44.      ULONG sm_BitMapHeight;
  45.      WORD  sm_LeftEdge;             /* Coordinates of requester on exit */
  46.      WORD  sm_TopEdge;
  47.      WORD  sm_Width;
  48.      WORD  sm_Height;
  49.      BOOL  sm_InfoOpened;           /* Info window opened on exit?      */
  50.      WORD  sm_InfoLeftEdge;         /* Last coordinates of Info window  */
  51.      WORD  sm_InfoTopEdge;
  52.      WORD  sm_InfoWidth;
  53.      WORD  sm_InfoHeight;
  54.      APTR  sm_UserData;             /* You can store your own data here */
  55.  };
  56.  
  57. The fields in this structure will be filled in with information obtained
  58. from the user.  This information can then be used in your application to
  59. create the type of screen that the user prefers. 
  60.  
  61.  
  62. Note that for most programs, the user's preferred screen mode can be
  63. determined from the Amiga's Preferences subsystem.  You do not have to use
  64. a screen mode requester.  Consider carefully whether it is more
  65. appropriate to use an ASL requester or to obtain the information directly
  66. from the settings in Overscan and ScreenMode Preferences. 
  67.  
  68. Listed below is a simple program that displays the new ASL screen mode
  69. requester including depth, width and height gadgets.  (This program
  70. requires the 2.1 version of the Amiga OS.)
  71.  
  72. ;/*
  73. LC -b1 -cfistq -v -y -j73 aslsm.c
  74. Blink FROM LIB:c.o,aslsm.o TO aslsm library LIB:lc.lib,lib:amiga.lib
  75. quit
  76. */
  77.  
  78.  
  79. #include <clib/all_protos.h>
  80. #include <exec/types.h>
  81. #include <libraries/asl.h>
  82. #include <utility/tagitem.h>
  83.  
  84. #define SMRTITLE ("Simplest ScreenMode Requester")
  85.  
  86. UBYTE *vers="\0$VER: ASL_ScreenMode_Requester 0.01 (8.7.92)";
  87.  
  88. struct Library *AslBase;
  89.  
  90.  
  91. void
  92. main(int argc, char **argv)
  93. {
  94.  
  95. struct ScreenModeRequester *smr;
  96. struct TagItem smrtags[5];
  97.  
  98. if( AslBase=OpenLibrary("asl.library", 38L) )
  99.     {
  100.     smrtags[0].ti_Tag=ASLSM_TitleText;
  101.     smrtags[0].ti_Data=(ULONG)SMRTITLE;
  102.  
  103.     smrtags[1].ti_Tag=ASLSM_DoWidth;
  104.     smrtags[1].ti_Data=TRUE;
  105.  
  106.     smrtags[2].ti_Tag=ASLSM_DoHeight;
  107.     smrtags[2].ti_Data=TRUE;
  108.  
  109.     smrtags[3].ti_Tag=ASLSM_DoDepth;
  110.     smrtags[3].ti_Data=TRUE;
  111.  
  112.     smrtags[4].ti_Tag=TAG_DONE;
  113.  
  114.     if( smr = (struct ScreenModeRequester *)
  115.           AllocAslRequest(ASL_ScreenModeRequest, smrtags) )
  116.         {
  117.         if( AslRequest(smr, 0L) )
  118.             {
  119.             printf("Display type: $%lx (see graphics/displayinfo.h)\n",
  120.                     smr->sm_DisplayID);
  121.             printf("Display width: %ld, height: %ld, depth: %d\n",
  122.                    smr->sm_DisplayWidth, smr->sm_DisplayHeight,
  123.                    smr->sm_DisplayDepth);
  124.             }              
  125.         else
  126.             printf("User cancelled or error...\n");  
  127.         
  128.         FreeAslRequest(smr);
  129.         }
  130.     CloseLibrary(AslBase);
  131.     }
  132. }
  133.  
  134.  
  135. As with other ASL requesters, the attributes of the screen mode requester
  136. are established using tag items when AllocAslRequest() is called.  These
  137. attributes can later be changed by using different tag items in the
  138. AslRequest() call. 
  139.  
  140. For instance, in the example above, tag items are used to specify that the
  141. screen mode requester should include gadgets for setting the display
  142. height (ASLSM_DoHeight), width (ASLSM_DoWidth) and depth (ASLSM_DoDepth). 
  143.  
  144.  
  145. Screen Mode Requester Tags
  146. ==========================
  147.  
  148. Here's a brief summary of the tag items that apply only to the ASL screen
  149. mode requester.  For a complete listing of all ASL tag items, refer to the
  150. ASL include files and Autodocs.
  151.  
  152. Screen Mode Tag Name            Used For
  153. --------------------            --------
  154. /* Window control */
  155. #define ASLSM_Window                  Parent window
  156. #define ASLSM_Screen                  Screen to open on if no window
  157. #define ASLSM_PubScreenName           Name of public screen
  158. #define ASLSM_PrivateIDCMP            Allocate private IDCMP?
  159. #define ASLSM_IntuiMsgFunc            Function to handle IntuiMessages
  160. #define ASLSM_SleepWindow             Block input in ASLSM_Window?
  161. #define ASLSM_UserData               What to put in sm_UserData
  162.  
  163. /* Text display */
  164. #define ASLSM_TextAttr                  Text font to use for gadget text
  165. #define ASLSM_Locale                Locale ASL should use for text
  166. #define ASLSM_TitleText               Title of requester
  167. #define ASLSM_PositiveText            Positive gadget text
  168. #define ASLSM_NegativeText          Negative gadget text
  169.  
  170. /* Initial settings */
  171. #define ASLSM_InitialLeftEdge         Initial requester coordinates
  172. #define ASLSM_InitialTopEdge
  173. #define ASLSM_InitialWidth        Initial requester dimensions
  174. #define ASLSM_InitialHeight
  175. #define ASLSM_InitialDisplayID        Initial display mode id
  176. #define ASLSM_InitialDisplayWidth      Initial display width
  177. #define ASLSM_InitialDisplayHeight     Initial display height
  178. #define ASLSM_InitialDisplayDepth      Initial display depth
  179. #define ASLSM_InitialOverscanType      Initial type of overscan
  180. #define ASLSM_InitialAutoScroll        Initial autoscroll setting
  181. #define ASLSM_InitialInfoOpened        Info window initially opened?
  182. #define ASLSM_InitialInfoLeftEdge     Initial Info window coords.
  183. #define ASLSM_InitialInfoTopEdge
  184.  
  185. /* Options */
  186. #define ASLSM_DoWidth                 Display Width gadget?
  187. #define ASLSM_DoHeight                Display Height gadget?
  188. #define ASLSM_DoDepth                 Display Depth gadget?
  189. #define ASLSM_DoOverscanType          Display Overscan Type gadget?
  190. #define ASLSM_DoAutoScroll            Display AutoScroll gadget?
  191.  
  192. /* Filtering */
  193. #define ASLSM_PropertyFlags           Must have these Property flags
  194. #define ASLSM_PropertyMask            Only these should be looked at
  195. #define ASLSM_MinWidth                  Minimum display width to allow
  196. #define ASLSM_MaxWidth                  Maximum display width to allow
  197. #define ASLSM_MinHeight               Minimum display height to allow
  198. #define ASLSM_MaxHeight               Maximum display height to allow
  199. #define ASLSM_MinDepth                  Minimum display depth
  200. #define ASLSM_MaxDepth                  Maximum display depth
  201. #define ASLSM_FilterFunc              Function to filter mode id's
  202.  
  203. #define ASLSM_CustomSMList            Exec list of struct DisplayMode
  204.  
  205.  
  206.  
  207. Other New ASL Tags in 2.1
  208. =========================
  209.  
  210. The tag items used to control the behavior of ASL requesters have been
  211. overhauled for the 2.1 release of the Amiga OS.  This section summarizes
  212. the new 2.1 tags. 
  213.  
  214.  
  215. New ASL Tags Used by All Requester Types
  216. ========================================
  217.  
  218. These tags apply to all three types of ASL requesters: the file requester,
  219. the font requester and the new screen mode requester.  Each tag in the
  220. list below is prepended with ASLxx_.  The actual tag names used by ASL
  221. will be prepended with ASLFR_, ASLFO_ or ASLSM_ depending on what type of
  222. requester is being used. 
  223.  
  224. New 2.1 Tag Name        Used For
  225. ----------------    --------
  226. ASLxx_PubScreenName     Name of a public screen on which to open the
  227.             requester. 
  228. ASLxx_Screen            Pointer to a screen on which to open the requester. 
  229. ASLxx_PrivateIDCMP      Specifies separate IDCMP for the requester
  230.             window (this replaces
  231.             the FILF_NEWIDCMP and FONF_NEWIDCMP flags in the
  232.              ASL_FuncFlags tag used in V37).  
  233. ASLxx_IntuiMsgFunc      Function to call when an unknown message arrives
  234.             at a shared IDCMP used by the requester window
  235.             (this replaces the ASL_HookFunc tag and the
  236.             FILF_DOMSGFUNC and FONF_DOMSGFUNC flags in the
  237.             ASL_FuncFlags used in V37). 
  238. ASLxx_SleepWindow       Modal requester.  Specifies that input should be
  239.             blocked in the parent window.
  240. ASLxx_UserData          A 32-bit value copied into the user data field of
  241.             the requester structure. 
  242. ASLxx_TextAttr          Font to use for requester window gadgets and menus.
  243. ASLxx_Locale            Locale (and language) to use for the requester
  244.             window. 
  245. ASLxx_FilterFunc        Function to call for each item (file, font or
  246.             mode) encountered.  If the function returns TRUE,
  247.             the item is displayed in the list view gadget,
  248.             otherwise it is rejected and not displayed.
  249.             (This replaces the ASL_HookFunc tag and the
  250.             FILF_DOWILDFUNC and FONF_DOWILDFUNC flags in
  251.             ASL_FuncFLags used in V37.)
  252.  
  253.  
  254.  
  255. New ASL Tags Used by the File Requester
  256. =======================================
  257.  
  258. These new 2.1 tag items apply only to file requesters:
  259.         
  260. New 2.1 Tag Name        Used For
  261. ----------------    --------
  262. ASLFR_DoSaveMode        Specifies that this file requester is a save
  263.             requester (this replaces the FILF_SAVE flag in
  264.             the ASL_FuncFlags tag used in V37).
  265. ASLFR_DoMultiSelect     Enables multiple selection of files
  266.             (this replaces the FILF_MULTISELECT flag in
  267.             ASL_FuncFlags used in V37).
  268. ASLFR_DoPatterns        Causes a pattern gadget to be included in the
  269.             requester (this replaces the FILF_PATGAD flag
  270.             in ASL_FuncFlags used in V37). 
  271. ASLFR_DrawersOnly       Causes the requester to only display drawers
  272.             (this replaces the FIL1F_NOFILES flag in
  273.             ASL_ExtFlags1 used in V37).
  274. ASLFR_RejectIcons       Causes the requester not to display Workbench icons. 
  275. ASLFR_RejectPattern     Specifies an AmigaDOS pattern used to reject files. 
  276. ASLFR_AcceptPattern     Specifies an AmigaDOS pattern used to accept files. 
  277. ASLFR_FilterDrawers     Makes ASLFR_RejectPattern and ASLFR_AcceptPattern
  278.              apply to drawer names.
  279.  
  280.  
  281.  
  282. New ASL Tags Used by the Font Requester
  283. =======================================
  284.  
  285. These new 2.1 tags apply only to font requesters.  The ASL Autodocs list
  286. most of these as new tag items for V38.  However there are no new features
  287. with most of these tags, just new, more consistent names. 
  288.  
  289. New 2.1 Tag Name          Used For
  290. ----------------    --------
  291. ASLFO_DoFrontPen     Causes the requester to display the Front Color
  292.             selection gadget
  293.             (this replaces the FONF_FRONTCOLOR flag in
  294.             ASL_FuncFlags used in V37). 
  295. ASLFO_DoBackPen        Causes the requester to display the Back Color
  296.             selection gadget (this replaces the FONF_BACKCOLOR
  297.             flag in ASL_FuncFlags used in V37). 
  298. ASLFO_DoStyle         Causes the requester to display Style checkbox
  299.             gadgets (this replaces the FONF_STYLES flag in
  300.             ASL_FuncFlags used in V37).
  301. ASLFO_DoDrawMode    Causes the requester to display the Mode cycle
  302.             gadget.(this replaces the FONF_DRAWMODE flag in
  303.             ASL_FuncFlags used in V37).
  304. ASLFO_FixedWidthOnly    Causes the requester to list only fixed-width
  305.             fonts (this replaces the FONF_FIXEDWIDTH flag
  306.             in ASL_FuncFlags  used in V37).
  307. ASLFO_InitialDrawMode     Initial setting of the font Mode gadget.
  308.  
  309.  
  310.  
  311.  
  312. New Tag Names for Old Features
  313. ==============================
  314. Many of the new tag items in the asl.h header file do not provide any new
  315. 2.1 features.  They just make the naming conventions used by ASL more
  316. consistent.  This section lists the new tag names along with the
  317. corresponding tag name used previously in V37 and earlier versions of the
  318. OS. 
  319.  
  320. In this first list each tag is prepended with ASLxx_.  The actual tag
  321. names used by ASL will be prepended with ASLFR_, ASLFO_ or ASLSM_
  322. depending on what type of requester is being used. 
  323.  
  324. New 2.1 Tag Name          Old Tag Name    Used For
  325. ----------------    ------------    --------
  326. ASLxx_Window              ASL_Window    Specifies the parent window of
  327.                     the requester.
  328. ASLxx_TitleText           ASL_Hail           String to use for the requester
  329.                     title.
  330. ASLxx_PositiveText        ASL_OKText     String to use for the OK button.
  331. ASLxx_NegativeText        ASL_CancelText    String to use for the  Cancel
  332.                     button.
  333.  
  334. ASLxx_InitialLeftEdge     ASL_LeftEdge    These specify the size and
  335. ASLxx_InitialTopEdge     ASL_TopeEdge    position of the requester.
  336. ASLxx_InitialWidth        ASL_Width
  337. ASLxx_InitialHeight       ASL_Height
  338.  
  339.  
  340.  
  341.  
  342.  
  343. This set of ASL tags apply only to file requesters:
  344.  
  345. New 2.1 Tag Name          Old Tag Name    Used For
  346. ----------------    ------------    --------
  347. ASLFR_InitialFile    ASL_File    Initial file name selection.
  348. ASLFR_InitialDrawer    ASL_Dir        Initial directory name selection.
  349. ASLFR_InitialPattern    ASL_Pattern    Initial pattern-matching string.
  350. ASLFR_Flags1        ASL_Flags    Various file requester options.
  351. ASLFR_Flags2        ASL_ExtFlags1    Various file requester options.
  352. ASLFR_HookFunc        ASL_HookFunc    User function for inspecting list
  353.                     view gadget entries or handling
  354.                     shared IDCMP messages.
  355.  
  356.  
  357.  
  358. This set of ASL tags applies only to font requesters:
  359.  
  360. New 2.1 Tag Name          Old Tag Name    Used For
  361. ----------------    ------------    --------
  362. ASLFO_InitialName    ASL_FontName    Initial font name selection.
  363. ASLFO_InitialSize         ASL_FontHeight  Initial font size.
  364. ASLFO_InitialFrontPen     ASL_FrontPen    Initial setting of Front Color
  365.                     gadget. 
  366. ASLFO_InitialBackPen      ASL_BackPen     Initial setting of Back Color
  367.                     gadget.
  368. ASLFO_InitialStyle        ASL_FontStyles  Initial setting of font Style
  369.                     gadget.
  370. ASLFO_ModeList            ASL_ModeList    Alternate strings for Mode
  371.                     cycle gadget.
  372. ASLFO_MaxHeight           ASL_MaxHeight   Specifies the maximum height of
  373.                     fonts to be listed.
  374. ASLFO_MinHeight           ASL_MinHeight   Specifies the minimum height of
  375.                     fonts to be listed.
  376. ASLFO_HookFunc            ASL_HookFunc    User function for inspecting
  377.                     list view gadget entries or
  378.                     handling shared IDCMP messages.
  379. ASLFO_Flags               ASL_Flags       Various font requester options.
  380.  
  381.  
  382.  
  383.  
  384.  
  385. The ASL Library and Amiga OS 2.1
  386. ================================
  387.  
  388. Developer Release NotesThe ASL Library and 2.1Amiga OS 2.1
  389.  
  390. Release Notes
  391.  
  392. This is the initial setting of the display Mode list view gadget.
  393. (Display mode IDs are defined in <graphics/displayinfo.h>.)
  394.     
  395.  
  396. These tags specify whether the screen mode requester should include a
  397. width numeric slider gadget and what values to use for its initial,
  398. maximum and minimum setting. 
  399.  
  400. These tags specify whether the screen mode requester should include a
  401. height numeric gadget and what values to use for its initial, maximum and
  402. minimum setting. 
  403.  
  404.  
  405. These tags specify whether the screen mode requester should include a
  406. depth numeric gadget and what values to use for its initial, maximum and
  407. minimum setting. 
  408.  
  409. These tags specify whether the screen mode requester should include an
  410. Overscan Type cycle gadget and what its initial setting should be. 
  411.  
  412. These tags specify whether the screen mode requester should include an
  413. Autoscroll checkbox gadget and its initial state. 
  414.  
  415. These tags specify whether the screen mode requester should appear with
  416. the Property window open and the values to use for its initial position.
  417. Note that this window is always accesible from the screen mode requester's
  418. menu. 
  419.  
  420. These two tags together provide a way to filter the display mode
  421. properties that will appear in the Property window. 
  422.  
  423. A custom Exec list of modes to let the user choose from.
  424.