home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / h_doc / Window < prev   
Encoding:
Text File  |  1997-01-17  |  14.2 KB  |  365 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    Window.h
  12.     Author:  Copyright © 1992, 1993, 1994, 1995 Jason Williams, Cy Booker 
  13.                                                 and Sergio Monesi, 
  14.                                                 Mike Smith
  15.     Version: 1.14 (10 Nov 1995)
  16.     Purpose: High-level window management functions
  17.     History: 1.10 (Dec 1994) Jason Williams
  18.              1.11 (05 Mar 1995) - CB - Desk_Window_GetInfo3() now returns 
  19.                                        (Desk_os_error *). 
  20.                                        Added Desk_Window_GainCaret()
  21.              1.12 (14 Jul 1995) - SM - Added Desk_Window_CreateOrig(), 
  22.                                        Desk_Window_DeleteOrig() and
  23.                                        Desk_Window_ForceWholeRedraw()
  24.              1.13 (26 Jul 1995) - SM - Added Desk_Window_MoveWindow()
  25.              1.14 (10 Nov 1995) - MS - Added Desk_Window_IsOpen
  26. */
  27.  
  28.  
  29. #ifndef __Desk_Window_h
  30. #define __Desk_Window_h
  31.  
  32. #ifdef __cplusplus
  33.     extern "C" {
  34. #endif
  35.  
  36. #ifndef __Desk_Wimp_h
  37.     #include "Desk.Wimp.h"
  38. #endif
  39.  
  40. #ifndef __Desk_WimpSWIs_h
  41.     #include "Desk.WimpSWIs.h"
  42. #endif
  43.  
  44. #ifndef __Desk_Pointer_h
  45.     #include "Desk.Pointer.h"
  46. #endif
  47.  
  48. #ifndef __Desk_Coord_h
  49.     #include "Desk.Coord.h"
  50. #endif
  51.  
  52.  
  53. typedef enum
  54. {
  55.   Desk_open_WHEREVER,             /* As defined in the window template file */
  56.   Desk_open_CENTERED,             /* center of screen */
  57.   Desk_open_CENTEREDUNDERPOINTER, /* Center window on pointer position */
  58.   Desk_open_OVERCARET,            /* Over the current caret position. NOTE: If no
  59.                                 caret, window is opened Desk_open_CENTERED */
  60.   Desk_open_UNDERPOINTER,         /* Under the current pointer position (so that
  61.                                 the pointer is then in TL corner of window */
  62.   Desk_open_NEARLAST              /* Slightly offset from the T.L. pos of the last
  63.                                 window to be opened with Desk_Window_Show  */
  64. } Desk_window_openpos;
  65.  
  66.  
  67.  
  68. extern Desk_window_handle Desk_Window_Create(const char *windowname, int maxtitlesize);
  69. /*
  70.  * This finds the named window template and creates a new copy of the window.
  71.  * It also records the memory allocated for the window so that it can be
  72.  * deallocated when the window is closed (using Desk_Window_Delete)
  73.  *
  74.  * "maxtitlesize" is the maximum length the window's title will be allowed
  75.  * grow to. (See Template.h: Desk_Template_Clone())
  76.  *
  77.  * Returns: The WIMP handle of the newly-created window, or 0 if the template
  78.  * for this window could not be found
  79.  */
  80.  
  81.  
  82. extern Desk_window_handle Desk_Window_CreateOrig(const char *windowname);
  83. /*
  84.  * This finds the named window template and creates the window using the
  85.  * data from the template directly (ie. withoud doing a copy).
  86.  * Window created with Desk_Window_CreateOrig should never be deleted but if you
  87.  * want to delete them you must use Desk_Window_DeleteOrig, not Desk_Window_Delete,
  88.  * otherwise the program may crash due to memory deallocation problems.
  89.  *
  90.  * Returns: The WIMP handle of the newly-created window, or 0 if the template
  91.  * for this window could not be found
  92.  */
  93.  
  94.  
  95. extern void Desk_Window_Show(Desk_window_handle window, Desk_window_openpos openpos);
  96. /*
  97.  
  98.  * This opens the given window on-screen in the desired position.
  99.  * (It can be used with ANY window, even if not created with Desk_Window_Create)
  100.  */
  101.  
  102.  
  103. extern Desk_window_handle Desk_Window_CreateAndShow(const char *windowname,
  104.                                           int  maxtitlesize,
  105.                                           Desk_window_openpos openpos);
  106. /*
  107.  * Simply calls Desk_Window_Create() and then Desk_Window_Show()
  108.  * (Just to make your programs slightly tidier)
  109.  */
  110.  
  111.  
  112. #define Desk_Window_Hide(handle) Desk_Wimp_CloseWindow(handle)
  113. /*
  114.  * Closes the specified window (removes it from screen)
  115.  * THE WINDOW IS NOT DELETED, just "hidden". It is preferable that you use
  116.  * Desk_Window_Create() and Desk_Window_Delete() every time you want a window to
  117.  * appear/disappear, to avoid problems.
  118.  *
  119.  * extern void Desk_Window_Hide(Desk_window_handle window);
  120.  */
  121.  
  122.  
  123. extern void Desk_Window_Delete(Desk_window_handle window);
  124. /*
  125.  * This Hides and deletes ANY window.
  126.  * It also removes any Event handlers attached to the window.
  127.  * If the window was created with Desk_Window_Create(), then it also deallocates
  128.  * any memory used by the window.
  129.  */
  130.  
  131.  
  132. extern void Desk_Window_DeleteOrig(Desk_window_handle window);
  133. /*
  134.  * This Hides and deletes a window created with Desk_Window_CreateOrig
  135.  * It also removes any Event handlers attached to the window.
  136.  * If the window was created using Desk_Window_Create you *must* use Desk_Window_Delete.
  137.  */
  138.  
  139.  
  140. extern void Desk_Window_GetInfo(Desk_window_handle window, Desk_window_info *result);
  141. /*
  142.  * This is simply a frontend to the Desk_Wimp_GetWindowInfo call. However, it
  143.  * returns the Window info block with the icon definitions STRIPPED.
  144.  * Thus, you can use a Desk_window_info structure in your local variables without
  145.  * having to allocate enough memory to cope with any icons that the window
  146.  * happens to have in it. This is the old, slow, nasty RISC OS 2 compatible
  147.  * version of this function. See Desk_Window_GetInfo3 (below) for RISC OS 3
  148.  * specialness
  149.  */
  150.  
  151.  
  152. extern void    Desk_Window_GetInfo3(Desk_window_handle window, Desk_window_info *result);
  153. /*
  154.  * This is simply a frontend to the Desk_Wimp_GetWindowInfo call. However, it
  155.  * returns the Window info block with the icon definitions STRIPPED.
  156.  * Thus, you can use a Desk_window_info structure in your local variables without
  157.  * having to allocate enough memory to cope with any icons that the window
  158.  * happens to have in it.
  159.  *
  160.  * This version is a smaller, tidier, faster version of the GetInfo call
  161.  * which makes use of a new feature of the SWI, available only under RISC OS 3
  162.  */
  163.  
  164.  
  165. extern void Desk_Window_ParentName(Desk_window_handle window, char *windowname);
  166. /*
  167.  * Given any window's handle, this function attempts to find the name
  168.  * (8 characters only, truncated if necessary) of the template from which
  169.  * the window was created (only works if created with Desk_Window_Create)
  170.  * - if the window handle is a negative number, "iconbar" is returned.
  171.  */
  172.  
  173.  
  174. extern Desk_bool Desk_Window_AutoHelp(Desk_window_handle window, Desk_icon_handle icon);
  175. /*
  176.  * This adds an event handler for the given window and icon (Desk_event_ANY and
  177.  * Desk_window_ICONBAR may be used). Every HelpRequest message thereafter
  178.  * received for that window will be answered (if possible) with a message
  179.  * from your messages (see Msgs) file.
  180.  * The message tag used will be constructed from the window's template-name
  181.  * and the icon number, as in:
  182.  *    mainwind.-1   - Any part of the window not covered by an icon
  183.  *    mainwind.3    - Icon 3 of any window created from "mainwind" template
  184.  *
  185.  * In the messages file, you can also use a catch-all message of:
  186.  *    mainwind.*
  187.  * which will catch ALL helprequests for the window, so ANY part of the
  188.  * window is guaranteed to give help (if no specific help for an icon is
  189.  * found, then the catch-all help will be used)
  190.  *
  191.  * NOTE that this function (Window.AutoHelp.c) may be recompiled to use
  192.  * Desk_EventMsg_Claim rather than Desk_Event_Claim if you so desire. However,
  193.  * note that currently EventMsg ignores the icon handle.
  194.  * EventMsg is more efficient than having multiple Desk_Event_Claims on
  195.  * incoming message events (especially when you add individual handlers for
  196.  * single windows/icons), but ONLY if you are using several message event
  197.  * handlers. Thus, the default here is to use Desk_Event_Claim so as to not
  198.  * "pull in" the code for EventMsg unless you want to use it.
  199.  */
  200.  
  201.  
  202. extern Desk_bool Desk_Window_HelpHandler(Desk_event_pollblock *event, void *reference);
  203. /*
  204.  * This is an event handler (added with Desk_Window_AutoHelp) which provides
  205.  * help on windows and their icons.
  206.  * If you wish to augment the help available for a window, you can call
  207.  * this handler yourself. Checking if it returns Desk_bool_TRUE or Desk_bool_FALSE gives an
  208.  * indicator of whether or not a help reply has been sent.
  209.  * Generally, you will check if the pointer is in an area of the window
  210.  * and supply help for that special area - if not, you drop back to a
  211.  * "fallback" position, and allow the "default" action, by callinf this
  212.  * handler.
  213.  * The other method is to add your own specialised help handler with
  214.  * Desk_Event_Claim, and then add this handler, so that your handler gets first
  215.  * choice when the event comes in.
  216.  */
  217.  
  218.  
  219. extern void Desk_Window_ModeChange(void);
  220. /*
  221.  * This function will go through all your templates and all windows that
  222.  * were created with Desk_Window_ calls, and re-find their outline fonts so
  223.  * that they are displayed correctly - this needs to be done after some
  224.  * mode changes. See Handler.h - Desk_Handler_ModeChangeWithFonts() to see
  225.  * how this should/can be used.
  226.  *
  227.  * NOTE: If you create ANY windows without using Desk_Window_Create calls, then
  228.  * this function will not fix their outline font use - but MUCH MORE
  229.  * IMPORTANTLY it will release the font, which may later be replaced
  230.  * by another font (or worse, cease to exists totally), so strange or
  231.  * unhealthy effects might ensue. i.e. ONLY use this if using Desk_Window_Create.
  232.  *
  233.  * Note also that this does NOT attempt to fix fonts in window titles
  234.  * because
  235.  *  a) The WIMP currently gets antialiased fonts *very* wrong with toolsprites
  236.  *     and/or titlebar selection, so they aren't recommended
  237.  *  b) Acorn DO have a new WIMP which uses an Outline font instead of system,
  238.  *     so the problem WILL go away with the next OS release.
  239.  *  c) This would involve re-creating the window, which would mean a possible
  240.  *     change in the window handle, which is something we can't do.
  241.  */
  242.  
  243.  
  244. extern void Desk_Window_SetTitle(Desk_window_handle window, const char *title);
  245. /*
  246.  * (equivalent of RISC OS Lib's Desk_win_settitle, only far better)
  247.  * This sets the text in the titlebar of the given window to the given string
  248.  *
  249.  * NOTE that if the title is not indirected, It will be unable to change
  250.  * the text, i.e. nothing will happen!
  251.  *
  252.  * It has several advantages over Desk_win_settitle, however:
  253.  *  + It uses legal OS calls to work out the rectange to redrawm so works
  254.  *    properly even with strange sized toolsprite sets
  255.  *  + It doesn't try to redraw anything if the window is CLOSED!
  256.  *  + It handles indirected and text-only title icons, rather than bombing
  257.  *    completely if the titlebar is not indirected.
  258.  *  + It actually terminates the string if it was too long to fit!!!
  259.  *
  260.  *  (And people wonder why I think ROLib is a load of excrement!)
  261.  *
  262.  *  Unfortunately it is not possible to only invalidate the VISIBLE area
  263.  *  of the window, so this may still create the occasional flicker of any
  264.  *  windows over the top of your titlebar... this can't be helped.
  265.  */
  266.  
  267.  
  268. extern void Desk_Window_BringToFront(Desk_window_handle window);
  269. /*
  270.  *  Pulls the given window to the front of the window stack
  271.  */
  272.  
  273.  
  274. #define Desk_Window_ConstrainMouse(WND) (Desk_Pointer_RestrictToWindow(WND))
  275. /*
  276.  *  Constrains the mouse pointer to the window bounds
  277.  *    extern Desk_os_error *Desk_Window_ConstrainMouse(Desk_window_handle window);
  278.  */
  279.  
  280.  
  281. extern void Desk_Window_SetExtent(Desk_window_handle wh, int x0, int y0, int x1, int y1);
  282. /*
  283.  *  Change the size of a window's work area extent.
  284.  *  If the window is open on screen, Desk_Wimp_OpenWindow will be automatically
  285.  *  called to force the change to be realised on screen
  286.  */
  287.  
  288.  
  289. extern void Desk_Window_ForceRedraw(Desk_window_handle wh,
  290.                                int x0, int y0, int x1, int y1);
  291. /*
  292.  *  Marks a screen area for redraw by the Wimp.
  293.  *  (x0, y0) is the bottom left corner.
  294.  *  Work Area coordinates, ie the top-left corner is generally 0, 0 with y
  295.  *  increasingly negative working down the screen.
  296.  *
  297.  *  Essentially just a veneer for Desk_Wimp_ForceRedraw().
  298.  */
  299.  
  300.  
  301. extern void Desk_Window_GetCoords(Desk_window_handle wh, Desk_convert_block *coords);
  302. /*
  303.  *  The coords 'Desk_convert_block' passed into this function is filled
  304.  *  with the relevant info for window 'wh'.
  305.  */
  306.  
  307.  
  308. extern void    Desk_Window_GainCaret(Desk_window_handle window);
  309. /*
  310.  * this intelligently gives the specified window the input focus
  311.  * if the window is 0 then it loses any input focus
  312.  * if the window already has the input focus in an icon then nothing happens
  313.  * otherwise the first writable, non-deleted, non-shaded icon gains the caret
  314.  *
  315.  * see also: Desk_Wimp_SetCaretPosition(), Desk_Icon_SetCaret()
  316.  */
  317.  
  318.  
  319. extern void    Desk_Window_ForceWholeRedraw(Desk_window_handle window);
  320. /*
  321.  *  Forces the redraw of the window screen area
  322.  */
  323.  
  324.  
  325. extern Desk_bool Desk_Window_MoveWindow(Desk_event_pollblock *event, void *reference);
  326. /*
  327.  *  This function allows you to move a window by dragging any (or all)
  328.  *  of its icons. From the event hadler that deals with mouse clicks
  329.  *  you should call this function (passing the parameters you received)
  330.  *  for the icon(s) that you want to work like the title bar.
  331.  *  Remember to set the icon button type to Desk_iconbtype_CLICK (3).
  332.  *
  333.  *  If you want that all the icons work this way, you can just register
  334.  *  this function with the event module using:
  335.  *    Desk_Event_Claim(Desk_event_CLICK, handle, Desk_event_ANY,  Desk_Window_MoveWindow, ref);
  336.  *
  337.  *  In this case you should set all the icons and also the window
  338.  *  background to button type Desk_iconbtype_CLICK (3) so that you will be
  339.  *  able to move the window clicking in any point inside it.
  340.  *
  341.  *  Note that this function always returns Desk_bool_TRUE.
  342.  */
  343.  
  344.  
  345. Desk_bool Desk_Window_IsOpen( Desk_window_handle window);
  346. /*
  347. Returns Desk_bool_TRUE is the window is open, ot false if it is closed.
  348. Calls Desk_Error2_XHandle if an error occurs (eg window doesn't exist), and
  349. returns Desk_bool_FALSE is the error isn't handled.
  350.  */
  351.  
  352.  
  353.  
  354. void    Desk_Window_ToggleShow( Desk_window_handle window, Desk_window_openpos openpos);
  355. /*
  356. Calls Desk_Window_Hide if the window is already open, else calls
  357. Desk_Window_Show.
  358.  */
  359.  
  360. #ifdef __cplusplus
  361. }
  362. #endif
  363.  
  364. #endif
  365.