Documentation for Win32lib v0.70.18
Table of Contents

Utilities

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


  • proc addStyle( id, style )   Add a style to a control.
  • func getClipboard(integer format)   Retrieves data in the clipboard with this format
  • func getHandles()   Gets all the hWnd handles for every control created in your application.
  • func getRecent(integer owner_type)   Gets the most recently defined control of a specifc kind, and returns the requested id.
  • func getStyleFlags( id )   Retrieves the standard and extra style flags for a control.
  • 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 setClipboard(object data,integer format,integer is_handle,integer size)    Sets the clipboard to data using the other parameters.
  • proc shellExecute( command, file, style )   Launch a Windows application
  • func shellExecuteEx( object verb, sequence file, object params, object defdir, object style, object struct )   Launch a Windows application
  • func w32bounds(sequence items,integer flags)    Returns index(es) or value(s) of the minimal/maximal element in a sequence
  • proc w32Sleep(atom milliseconds)    Puts current thread to sleep for milliseconds milliseconds, if another OS thread is ready to run.

    Documentation for Win32lib v0.70.18
    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. It should not be combined with any other style.

    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: getClipboard, getHandles, getRecent, getStyleFlags, hitTestTT, playSound, removeStyle, setClipboard, shellExecute, shellExecuteEx, w32bounds, w32Sleep


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    getClipboard
    (integer format)

    Retrieves data in the clipboard with this format

    Returns: (OBJECT) Either a string for text formats, or a data handle otherwise.

    Category: Utilities

    If getting a data handle, you should not free it, and copy the referred contents to some other place, because you do not own the returned handle.

    See Also: addStyle, getHandles, getRecent, getStyleFlags, hitTestTT, playSound, removeStyle, setClipboard, shellExecute, shellExecuteEx, w32bounds, w32Sleep


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    getHandles
    ()

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

    Returns: A sequence of atoms.

    Category: Utilities

    Handles for destroyed controls, or controls that don't exist, appear as 0.

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

    See Also: addStyle, getClipboard, getRecent, getStyleFlags, hitTestTT, playSound, removeStyle, setClipboard, shellExecute, shellExecuteEx, w32bounds, w32Sleep


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    getRecent
    (integer owner_type)

    Gets the most recently defined control of a specifc kind, and returns the requested id.

    Returns: INTEGER: the id of the most recently created control of the specified type, or 0 if none was created so far.

    Category: Utilities

    The supported owner type specifications are:

  • w32RecentMenu: id of the most recently created menu, or 0;
  • w32RecentWindow: id of the most recently created window, or 0;
  • w32RecentTabControl: id of the most recently created TabControl, or 0;
  • w32RecentForms: id of the most recently created form window, or {-1}.

    See Also: addStyle, getClipboard, getHandles, getStyleFlags, hitTestTT, playSound, removeStyle, setClipboard, shellExecute, shellExecuteEx, w32bounds, w32Sleep


    Documentation for Win32lib v0.70.18
    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: addStyle, getClipboard, getHandles, getRecent, hitTestTT, playSound, removeStyle, setClipboard, shellExecute, shellExecuteEx, w32bounds, w32Sleep


    Documentation for Win32lib v0.70.18
    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: addStyle, getClipboard, getHandles, getRecent, getStyleFlags, playSound, removeStyle, setClipboard, shellExecute, shellExecuteEx, w32bounds, w32Sleep


    Documentation for Win32lib v0.70.18
    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: addStyle, getClipboard, getHandles, getRecent, getStyleFlags, hitTestTT, removeStyle, setClipboard, shellExecute, shellExecuteEx, w32bounds, w32Sleep


    Documentation for Win32lib v0.70.18
    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: addStyle, getClipboard, getHandles, getRecent, getStyleFlags, hitTestTT, playSound, setClipboard, shellExecute, shellExecuteEx, w32bounds, w32Sleep


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    setClipboard
    (object data,integer format,integer is_handle,integer size)

    Sets the clipboard to data using the other parameters.

    Returns: w32False on failure, w32True on success.

    Category: Utilities

    format is a clipboard format, for instance CF_TEXT. The way data is interpreted depends on the other parameters: If data is a sequence, and the format is any of CF_TEXT, CF_DSPTEXT, CF_OEMTEXT, CF_UNICODETEXT, then the procedure takes care of all the memory work, and is_handle is ignored. Otherwise, if is_handle is nonzero, it means that data is a Window memory handle. You may have acquired it through w32acquire_handle(). Otherwise, data points to the data you wish to send, and size is the size of the data buffer. For the CF_DIB and CF_PALETTE format, the routine is able to figure size out, and will do so if size is 0. Other formats may be supported in this way in the future. For the CF_BITMAP, private GDI formats, and formats, the only allowable value data may have is a handle, so that is_anndle and size are both ignored. If you provide a handle, you no longer own this handle on return.

    See Also: addStyle, getClipboard, getHandles, getRecent, getStyleFlags, hitTestTT, playSound, removeStyle, shellExecute, shellExecuteEx, w32bounds, w32Sleep


    Documentation for Win32lib v0.70.18
    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: addStyle, getClipboard, getHandles, getRecent, getStyleFlags, hitTestTT, playSound, removeStyle, setClipboard, shellExecuteEx, w32bounds, w32Sleep


    Documentation for Win32lib v0.70.18
    Table of Contents

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

    Launch a Windows application

    Returns: ATOM: Success code. 0 to 32 are errors; successful invocation returns a process handle.

    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 the parameters passed to the program. If there are no parameters then params should be 0
    If you need to pass parameters, params is either a string containing the parameters (as if typed on the console), or it is a list of zero or more parameters that can be strings or numbers. When using params as a list of parameters, any string in the list that contains spaces will be passed to the program enclosed in double-quotes.

    When opening an EXE file, params is the parameters for that program.

    When opening a document file instead of an EXE, params must be 0.

    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 used when you need to manage the memory allocation for the routine. This can be a performance advantage if the same shellExecute action is required repeatedly.
    If this is given as zero, then the routine allocates RAM for the other parameters and frees it again just before returning to your application. But if you supply either a single RAM address or a sequence of four RAM addresses, the routine uses your allocation and does not free any RAM. Instead it is your application's responsibility to free the RAM.
    When struct is supplied as a set of four RAM addresses, the routine assumes that they represent the RAM location of the verb, file, parms, and defdir strings (0-terminated) you have already set up.
    When struct is a single RAM address, the routine assumes that it points to a set of four RAM addresses as specified above. In the C programming langauge this would be equivalent to ...

       struct SEStrings {
          char *verb;
          char *file;
          char *parms;
          char *defdir;
       }
       struct SEStrings ms;
        * Example settings */
       ms.verb = "open";
       ms.file = "iexplorer.exe";
       ms.parms = 0;
       ms.defdir = 0;
    

    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

    Example 1:

      res = shellExecuteEx("open", "iexplorer", 0, 0, SW_NORMAL, 0)
    

    Example 2:

      atom pVerb = allocate_string("open")
      atom pFile = allocate_string("iexplorer.exe")
      res = shellExecuteEx(0, 0, 0, 0, SW_NORMAL, {pVerb, pFile, 0, 0})
    

    Example 3:

      atom pVerb = allocate_string("open")
      atom pFile = allocate_string("iexplorer.exe")
      atom pStruct = allocate(16) -- room for four 32-bit addresses.
      memset(pStruct, 16, 0)
      poke4(pStruct + 0, pVerb)
      poke4(pStruct + 4, pFile)
      res = shellExecuteEx(0, 0, 0, 0, SW_NORMAL, pStruct)
    

    Example 4:

      res = shellExecuteEx("open", "ex.exe", "dirutil -C c:\\temp\\ e:\\backup\\", 0, SW_NORMAL, 0)
    

    Example 5:

      res = shellExecuteEx("open", "ex.exe", {"dirutil", "-C", sourcedir, backupdir}, 0, SW_NORMAL, 0)
    

    See Also: addStyle, getClipboard, getHandles, getRecent, getStyleFlags, hitTestTT, playSound, removeStyle, setClipboard, shellExecute, w32bounds, w32Sleep


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32bounds
    (sequence items,integer flags)

    Returns index(es) or value(s) of the minimal/maximal element in a sequence

    Returns: (OBJECT) One or two indices, or one or two values, depending on flags.

    Category: Utilities

    flags is the sum of zero or more of:

  • w32BOUNDS_MIN=0: return a minimum index or value;
  • w32BOUNDS_MAX=1: return a maximum index or value;
  • w32BOUNDS_INDEX=0,
  • w32BOUNDS_VALUE=2,
  • w32BOUNDS_PAIR=4,
  • w32BOUNDS_INDEX_FIRST=w32BOUNDS_INDEX
  • w32BOUNDS_VALUE_FIRST=w32BOUNDS_VALUE Obviously, only some combinations make sense.

    See Also: addStyle, getClipboard, getHandles, getRecent, getStyleFlags, hitTestTT, playSound, removeStyle, setClipboard, shellExecute, shellExecuteEx, w32Sleep


    Documentation for Win32lib v0.70.18
    Table of Contents

    [proc]
    w32Sleep
    (atom milliseconds)

    Puts current thread to sleep for milliseconds milliseconds, if another OS thread is ready to run.

    Category: Utilities

    "thread" here refers to an OS thread, not to an Euphoria task. exw.exe runs two separate threads./n Passing a value of #FFFFFFFF puts the thread to sleep until some specific action is taken to wake the thread up./n Passing a value of 0 attempts to run another thread of same priority immediately./n Passing any other values puts the thread to sleep for that many milliseconds. If another thread has the same priority and is ready to run, it gets control.

    See Also: addStyle, getClipboard, getHandles, getRecent, getStyleFlags, hitTestTT, playSound, removeStyle, setClipboard, shellExecute, shellExecuteEx, w32bounds