Documentation for Win32lib v0.60.6
Table of Contents

Utilities

These are useful routines that don't seem to fit in any other category.


  • proc abortErr( sequence errorparam )   Display an error message, run any user-defined cleanup routines, and then abort.
  • proc addStyle( id, style )   Add a style to a control.
  • proc attachCleanUp( routine_id )   Establishes a user defined clean up routine which is invoked just prior to win32lib ending or aborting.
  • proc detachCleanUp( routine_id )   Removes a user defined clean up routine from the list of attached ones.
  • func fetch_CHARFORMAT(atom CHARFORMAT)   Extracts the data from a CHARFORMAT structure.
  • func fetch_SYSTEMTIME(atom SYSTEMTIME)   
  • func getHandles()   Gets all the hWnd handles for every control created in your application.
  • func getLocalTime()   Gets the date and time according to your timezone settings.
  • func getStyleFlags( id )   Retrieves the standard and extra style flags for a control.
  • func getSystemTime()   Gets the date and time as UTC (a.k.a. GMT)
  • func hitTestTT()   Tests to see if the mouse is currently over a control that has a tooltip.
  • func playSound( sequence FileParm )   Play the .WAV file.
  • proc removeStyle( id, style )   Remove a style from a control.
  • func setStartupFont( integer font )   Establishes the default font to use when creating a window or control.
  • proc setWarning( integer flag )   Shows or Hides warning messages from user.
  • proc shellExecute( command, file, style )   Launch a Windows application
  • func shellExecuteEx( object verb, sequence file, object params, object defdir, object style, atom struct )   Launch a Windows application
  • func struct_CHARFORMAT(dwMask,dwEffects,yHeight,yOffset,crTextColor,bCharSet,bPitchAndFamily,szFaceName)   Builds a CHARFORMAT structure and returns its address.
  • func struct_SYSTEMTIME(year,month,dayofweek,day,hour,minute,second,milliseconds)   
  • func struct_TOOLINFO(uFlags, hwnd, uId, rect, text )   
  • proc warnErr( sequence errorparam )   Display an error message, with option to abort.

    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    abortErr
    ( sequence errorparam )

    Display an error message, run any user-defined cleanup routines, and then abort.

    Category: Utilities

    errorparam can be either a text message or a two-element sequence in which the first is a text message and the second is an error code (integer).

    If any user-defined clean up routine have been attached, they are invoked prior to win32lib's own cleanup routine, then the application is aborted. See attachCleanUp() for details.

    Example:

           abortErr( {"The tape drive is not responding.", w32MsgNum + 17} )
    

    abortErr( "Fatal error. Bummer, dude." )

    See Also: addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    addStyle
    ( id, style )

    Add a style to a control.

    Category: Utilities

    If style is an atom then only the normal Windows style is modified, but if style is a sequence, it must be a two-atom sequence. The first is the normal styles, and the second is the extended styles.

    A special use of this is to set a control to close its parent window. To do this call the routine using the style w32AUTOCLOSE.

    Example

            addStyle(w1, {
                     -- normal styles
                     (WS_MINIMIZEBOX+WS_MAXIMIZEBOX+WS_THICKFRAME),
                     -- extended styles
                     (WS_EX_CLIENTEDGE)
                    })
          -- Set the control to close the window
          addStyle( BtnClose, w32AUTOCLOSE)
    

    See Also: abortErr, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    attachCleanUp
    ( routine_id )

    Establishes a user defined clean up routine which is invoked just prior to win32lib ending or aborting.

    Returns: (INTEGER) The number of clean up routines attached.

    Category: Utilities

    Allows the application to clean up when win32lib application is ending or detects an abort situation. It is possible to attach multiple clean up routines. If this is done, they are invoked by win32lib in order of most-recently-attached to first-attached, that is in reverse order that they were attached in.

    The clean up routine, when invoked by win32lib, is passed four parameters...

  • ErrorCode (integer) Zero if this is a normal end, or the code number for the error that is causing win32lib to abort.
  • ErrorText (sequence) The text displayed to the user.
  • ControlId (integer) The id of the current control (0 => no control is current).
  • LastCleanup (integer) A flag which is 1 if this is the last user defined cleanup routine to be invoked, and 0 if there are others still to be invoked.

    The clean up routine must return an integer flag. If the flag is -1, then no further attached clean up routines will be invoked before win32lib aborts, otherwise any other routines will be invoked. You only return -1 if you really do know what the side-effects will be.

    Example:

       function AppCleanUp(integer ErrCode, sequence ErrText, integer ControlId, integer LastCleanUp)
          . . .
          return 0 -- Continue with other clean up routines.
       end function
    

    -- Link in my clean-up routine cnt = attachCleanUp( routine_id("AppCleanUp" ))

    See Also: abortErr, addStyle, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    detachCleanUp
    ( routine_id )

    Removes a user defined clean up routine from the list of attached ones.

    Returns: If unsuccessful this returns -1, else the number of clean up routines still attached.

    Category: Utilities

    Example:

       integer cnt, CU_id
       . . .
       function AppCleanUp(integer ErrCode, sequence ErrText, integer ControlId, integer LastCleanUp)
          . . .
          return 0 -- Continue with other clean up routines.
       end function
    

    -- Link in my clean-up routine CU_id = routine_id("AppCleanUp" ) cnt = attachCleanUp( CU_id ) . . . cnt = detachCleanUp( CU_id )

    See Also: abortErr, addStyle, attachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    fetch_CHARFORMAT
    (atom CHARFORMAT)

    Extracts the data from a CHARFORMAT structure.

    Returns: A sequence containing the data fields.

    Category: Utilities

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    fetch_SYSTEMTIME
    (atom SYSTEMTIME)

    Category: Utilities

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    getHandles
    ()

    Gets all the hWnd handles for every control created in your application.

    Returns: A sequence of atoms.

    Category: Utilities

            addBtn = create(PushButton, "", 100,100, 40,40,0)
            allHandles = getHandles()
            otherfunc( allHandles[ addBtn ], ... )
    

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    getLocalTime
    ()

    Gets the date and time according to your timezone settings.

    Returns: SEQUENCE: The date and time (See below for details)

    Category: Utilities

    This does not need any parameters. The date and time are returned based on your system's current timezone settings.

    The return sequence has eight elements arranged thus

  • Year
  • Month
  • DayOfWeek
  • Day
  • Hour
  • Minute
  • Second
  • Milliseconds

    Example:

          sequence tm
          tm = getLocalTime()
    

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    getStyleFlags
    ( id )

    Retrieves the standard and extra style flags for a control.

    Returns: SEQUENCE: {ATOM: standard, ATOM: extra}

    Category: Utilities

    Example

          sequence lFlags
          lFlags = getStyleFlags(myButton)
    

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    getSystemTime
    ()

    Gets the date and time as UTC (a.k.a. GMT)

    Returns: SEQUENCE: The date and time (See below for details)

    Category: Utilities

    This does not need any parameters. The date and time are returned as UTC (Coordinated Universal Time) which is the old Greenwich Mean Time.

    The return sequence has eight elements arranged thus

  • Year
  • Month
  • DayOfWeek
  • Day
  • Hour
  • Minute
  • Second
  • Milliseconds

    Example:

          sequence tm
          tm = getSystemTime()
    

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    hitTestTT
    ()

    Tests to see if the mouse is currently over a control that has a tooltip.

    Returns: w32False or the id of a control.

    Category: Utilities

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, playSound, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    playSound
    ( sequence FileParm )

    Play the .WAV file.

    Returns: w32True if succeeds, w32False if fails.

    Category: Utilities

    This is a wrapper around the Win32 PlaySound command.
    FileName can take one of four forms.

  • The value 0 or an empty sequence. Use this to immediately stop playing any sound.
  • A simple filename, such as a ".WAV" file to play. This sets up the flags as SND_FILENAME and SND_ASYNC.
  • The form {FileName, Flags} which gives you more control over the flag settings. The Flags can be either a single atom or a sequence of sound flags.
  • The form {FileName, Flags, ResourceId} is available the sound you need to play is contained in the resources of an executable file. In this case FileName is is a sequence with one element in it; a handle to an executable file. ResourceId is the id of the resource to play.

    Example:

          -- Play a sound file and return before it ends.
          VOID = playSound("announce.wav")
    

    -- Play a sound file and wait until it ends. VOID = playSound({"announce.wav",{SND_FILENAME,SND_SYNC})

    -- Play a sound file continuously in the background VOID = playSound({"background.wav", {SND_FILENAME,SND_ASYNC,SND_LOOP})

    -- Play a sound file but only if no other sound is already playing. VOID = playSound({"hit.wav",{SND_FILENAME,SND_ASYNC,SND_NOSTOP})

    -- Play a sound named in the system registry. VOID = playSound({"MailBeep",{SND_ALIAS})

    -- Stop playing any sound. VOID = playSound({"",SND_PURGE}) -- or VOID = playSound(0)

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    removeStyle
    ( id, style )

    Remove a style from a control.

    Category: Utilities

    If style is an atom then only the normal Windows style is modified, but if style is a sequence, it must be a tw-atom sequence. The first is the normal styles, and the second is the extended styles.

    Example

            removeStyle(w1, {
                     -- normal styles
                     (WS_MINIMIZEBOX+WS_MAXIMIZEBOX+WS_THICKFRAME),
                     -- extended styles
                     (WS_EX_CLIENTEDGE)
                       })
    

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    setStartupFont
    ( integer font )

    Establishes the default font to use when creating a window or control.

    Category: Utilities

    font is one of the system constants...

  • OEM_FIXED_FONT
  • ANSI_FIXED_FONT
  • ANSI_VAR_FONT
  • SYSTEM_FONT
  • DEVICE_DEFAULT_FONT
  • SYSTEM_FIXED_FONT

    Example

         setStartupFont(SYSTEM_FIXED_FONT)
    

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    setWarning
    ( integer flag )

    Shows or Hides warning messages from user.

    Category: Utilities

    Since 'warning' messages (triggered by warnErr) are only warnings and not fatal, it may be advantageous to suppress them in an application.

    The flag maybe one of ...

  • 0 To hide warning messages
  • 1 To show warning messages, giving the option to continue or quit.
  • 2 To turn all warning messages into fatal errors instead.

    By default, the setting is 1 Example:

          -- suppress warning messages
          setWarning( 0 )
    

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    shellExecute
    ( command, file, style )

    Launch a Windows application

    Category: Utilities

    This is a wrapper around the Win32 ShellExecute command. command is usually "open".
    file is the file or directory to open or run.
    style is usually SW_SHOWNORMAL, but can be SW_SHOWMINIMIZED or SW_SHOWMAXIMIZED

           -- Start up MSAcess on the database.
           shellExecute("open", "myDB.mdb", SW_SHOWNORMAL)
    

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    shellExecuteEx
    ( object verb, sequence file, object params, object defdir, object style, atom struct )

    Launch a Windows application

    Returns: INTEGER: Success code. 0 to 32 are errors.

    Category: Utilities

    This is a wrapper around the Win32 ShellExecute command.

    The verb parameter is the action you are trying to execute. In nearly all cases this is "open". The actions possible are defined in your Windows File Associations definitions. If this parameter is not a sequence then the default action for the file is used.

    The file parameter is the file to perform the action upon. This is usually a .EXE file but can be any file type that has a defined action in the Window File Associations.

    The params is a list of zero or more parameters passed to the file. Usually when opening an EXE file, this is the parameters for that program.

    The defdir is the default directory to change to before openning the file. If this is not a sequence the the current directory is used.

    The style parameter is a window style flag. These can be ...

  • SW_HIDE
  • SW_SHOWNORMAL
  • SW_NORMAL
  • SW_SHOWMINIMIZED
  • SW_SHOWMAXIMIZED
  • SW_MAXIMIZE
  • SW_SHOWNOACTIVATE
  • SW_SHOW
  • SW_MINIMIZE
  • SW_SHOWMINNOACTIVE
  • SW_SHOWNA
  • SW_RESTORE
  • SW_SHOWDEFAULT
  • SW_MAX

    The struct parameter is not used yet.

    The return codes for this function are...
    SE_ERR_FNF -- file not found SE_ERR_PNF -- path not found SE_ERR_ACCESSDENIED -- access denied SE_ERR_OOM -- out of memory SE_ERR_SHARE SE_ERR_ASSOCINCOMPLETE SE_ERR_DDETIMEOUT SE_ERR_DDEFAIL SE_ERR_DDEBUSY SE_ERR_NOASSOC SE_ERR_DLLNOTFOUND

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecute, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    struct_CHARFORMAT
    (dwMask,dwEffects,yHeight,yOffset,crTextColor,bCharSet,bPitchAndFamily,szFaceName)

    Builds a CHARFORMAT structure and returns its address.

    Returns: The address of a valid CHARFORMAT structure.

    Category: Utilities

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_SYSTEMTIME, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    struct_SYSTEMTIME
    (year,month,dayofweek,day,hour,minute,second,milliseconds)

    Category: Utilities

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_TOOLINFO, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    struct_TOOLINFO
    (uFlags, hwnd, uId, rect, text )

    Category: Utilities

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, warnErr


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    warnErr
    ( sequence errorparam )

    Display an error message, with option to abort.

    Category: Utilities

    errorparam can be either a text message or a two-element sequence in which the first is a text message and the second is an error code (integer).

    This routine will display a dialog window with three buttons.
    [ YES ] : If selected, the program will continue.
    [ NO ] : if pressed, the program will continue, but future warning about the same error will be ignored.
    [CANCEL]: if pressed, will stop the program running immediately.

    If any user-defined clean up routine have been attached, they are invoked prior to win32lib's own cleanup routine, if the application is aborted. See attachCleanUp() for details. Example:

          warnErr( "Bad data. Abort program?" )
    

    See Also: abortErr, addStyle, attachCleanUp, detachCleanUp, fetch_CHARFORMAT, fetch_SYSTEMTIME, getHandles, getLocalTime, getStyleFlags, getSystemTime, hitTestTT, playSound, removeStyle, setStartupFont, setWarning, shellExecute, shellExecuteEx, struct_CHARFORMAT, struct_SYSTEMTIME, struct_TOOLINFO