RISC DISC 1/RISC_DISC_1.iso/pd_share/code/desklib/!DeskLib/h/Window

Text File | 1994-05-29 | 9.3 KB | 212 lines

/*
    ####             #    #     # #
    #   #            #    #       #          The FreeWare C library for
    #   #  ##   ###  #  # #     # ###             RISC OS machines
    #   # #  # #     # #  #     # #  #   ___________________________________
    #   # ####  ###  ##   #     # #  #
    #   # #        # # #  #     # #  #    Please refer to the accompanying
    ####   ### ####  #  # ##### # ###    documentation for conditions of use
    ________________________________________________________________________

    File:    Window.h
    Author:  Copyright © 1992, 1993 Jason Williams
    Version: 1.03 (29 June 1993)
    Purpose: High-level window management functions
*/


#ifndef __dl_window_h
#define __dl_window_h

#ifndef __dl_wimp_h
#include "Wimp.h"
#endif


typedef enum
{
  open_WHEREVER,             /* As defined in the window template file */
  open_CENTERED,             /* center of screen */
  open_CENTEREDUNDERPOINTER, /* Center window on pointer position */
  open_OVERCARET,            /* Over the current caret position. NOTE: If no
                                caret, window is opened open_CENTERED */
  open_UNDERPOINTER,         /* Under the current pointer position (so that
                                the pointer is then in TL corner of window */
  open_NEARLAST              /* Slightly offset from the T.L. pos of the last
                                window to be opened with Window_Show  */
} window_openpos;



/* Window_Create -----------------------------------------------------------
 * This finds the named window template and creates a new copy of the window.
 * It also records the memory allocated for the window so that it can be
 * deallocated when the window is closed (using Window_Delete)
 *
 * "maxtitlesize" is the maximum length the window's title will be allowed
 * grow to. (See Template.h: Template_Clone())
 *
 * Returns: The WIMP handle of the newly-created window, or 0 if the template
 * for this window could not be found
 */
extern window_handle Window_Create(char *windowname, int maxtitlesize);


/* Window_Show -------------------------------------------------------------

 * This opens the given window on-screen in the desired position.
 * (It can be used with ANY window, even if not created with Window_Create)
 */
extern void Window_Show(window_handle window, window_openpos openpos);


/* Window_CreateAndShow ----------------------------------------------------
 * Simply calls Window_Create() and then Window_Show()
 * (Just to make your programs slightly tidier)
 */
extern window_handle Window_CreateAndShow(char *windowname,
                                          int  maxtitlesize,
                                          window_openpos openpos);


/* Window_Hide -------------------------------------------------------------
 * Closes the specified window (removes it from screen)
 * THE WINDOW IS NOT DELETED, just "hidden". It is preferable that you use
 * Window_Create() and Window_Delete() every time you want a window to
 * appear/disappear, to avoid problems.
 *
 * extern void Window_Hide(window_handle window);
 */
#define Window_Hide(handle) Wimp_CloseWindow(handle)


/* Window_Delete -----------------------------------------------------------
 * This Hides and deletes ANY window.
 * It also removes any Event handlers attached to the window.
 * If the window was created with Window_Create(), then it also deallocates
 * any memory used by the window.
 */
extern void Window_Delete(window_handle window);



/* Window_GetInfo ----------------------------------------------------------
 * This is simply a frontend to the Wimp_GetWindowInfo call. However, it
 * returns the Window info block with the icon definitions STRIPPED.
 * Thus, you can use a window_info structure in your local variables without
 * having to allocate enough memory to cope with any icons that the window
 * happens to have in it.
 */
extern void Window_GetInfo(window_handle window, window_info *result);


/* Window_ParentName -------------------------------------------------------
 * Given any window's handle, this function attempts to find the name
 * (8 characters only, truncated if necessary) of the template from which
 * the window was created (only works if created with Window_Create)
 * - if the window handle is a negative number, "iconbar" is returned.
 */
extern void Window_ParentName(window_handle window, char *windowname);


/* Window_AutoHelp ---------------------------------------------------------
 * This adds an event handler for the given window and icon (event_ANY and
 * window_ICONBAR may be used). Every HelpRequest message thereafter
 * received for that window will be answered (if possible) with a message
 * from your messages (see Msgs) file.
 * The message tag used will be constructed from the window's template-name
 * and the icon number, as in:
 *    mainwind.-1   - Any part of the window not covered by an icon
 *    mainwind.3    - Icon 3 of any window created from "mainwind" template
 *
 * In the messages file, you can also use a catch-all message of:
 *    mainwind.*
 * which will catch ALL helprequests for the window, so ANY part of the
 * window is guaranteed to give help (if no specific help for an icon is
 * found, then the catch-all help will be used)
 *
 * NOTE that this function (Window.AutoHelp.c) may be recompiled to use
 * EventMsg_Claim rather than Event_Claim if you so desire. However,
 * note that currently EventMsg ignores the icon handle.
 * EventMsg is more efficient than having multiple Event_Claims on
 * incoming message events (especially when you add individual handlers for
 * single windows/icons), but ONLY if you are using several message event
 * handlers. Thus, the default here is to use Event_Claim so as to not
 * "pull in" the code for EventMsg unless you want to use it.
 */
extern BOOL Window_AutoHelp(window_handle window, icon_handle icon);


/* Window_HelpHandler ------------------------------------------------------
 * This is an event handler (added with Window_AutoHelp) which provides
 * help on windows and their icons.
 * If you wish to augment the help available for a window, you can call
 * this handler yourself. Checking if it returns TRUE or FALSE gives an
 * indicator of whether or not a help reply has been sent.
 * Generally, you will check if the pointer is in an area of the window
 * and supply help for that special area - if not, you drop back to a
 * "fallback" position, and allow the "default" action, by callinf this
 * handler.
 * The other method is to add your own specialised help handler with
 * Event_Claim, and then add this handler, so that your handler gets first
 * choice when the event comes in.
 */
extern BOOL Window_HelpHandler(event_pollblock *event, void *reference);


/* Window_ModeChange -------------------------------------------------------
 * This function will go through all your templates and all windows that
 * were created with Window_ calls, and re-find their outline fonts so
 * that they are displayed correctly - this needs to be done after some
 * mode changes. See Handler.h - Handler_ModeChangeWithFonts() to see
 * how this should/can be used.
 *
 * NOTE: If you create ANY windows without using Window_Create calls, then
 * this function will not fix their outline font use - but MUCH MORE
 * IMPORTANTLY it will release the font, which may later be replaced
 * by another font (or worse, cease to exists totally), so strange or
 * unhealthy effects might ensue. i.e. ONLY use this if using Window_Create.
 *
 * Note also that this does NOT attempt to fix fonts in window titles
 * because
 *  a) The WIMP currently gets antialiased fonts *very* wrong with toolsprites
 *     and/or titlebar selection, so they aren't recommended
 *  b) Acorn DO have a new WIMP which uses an Outline font instead of system,
 *     so the problem WILL go away with the next OS release.
 *  c) This would involve re-creating the window, which would mean a possible
 *     change in the window handle, which is something we can't do.
 */
extern void Window_ModeChange(void);


/* Window_SetTitle ---------------------------------------------------------
 * (equivalent of RISC OS Lib's win_settitle, only far better)
 * This sets the text in the titlebar of the given window to the given string
 *
 * NOTE that if the title is not indirected, It will be unable to change
 * the text, i.e. nothing will happen!
 *
 * It has several advantages over win_settitle, however:
 *  + It uses legal OS calls to work out the rectange to redrawm so works
 *    properly even with strange sized toolsprite sets
 *  + It doesn't try to redraw anything if the window is CLOSED!
 *  + It handles indirected and text-only title icons, rather than bombing
 *    completely if the titlebar is not indirected.
 *  + It actually terminates the string if it was too long to fit!!!
 *
 *  (And people wonder why I think ROLib is a load of excrement!)
 *
 *  Unfortunately it is not possible to only invalidate the VISIBLE area
 *  of the window, so this may still create the occasional flicker of any
 *  windows over the top of your titlebar... this can't be helped.
 */
extern void Window_SetTitle(window_handle window, char *title);


/* Window_BringToFront -----------------------------------------------------
 *  Pulls the given window to the front of the window stack
 */
extern void Window_BringToFront(window_handle window);

#endif