activategadget() allows the program to activate a string gadget (and
certain custom gadgets).  if successful, this function has the same effect
as the user clicking the mouse select button when the mouse pointer is
within the gadget's select box and any subsequent keystrokes will effect
the gadget's string.

    BOOL ActivateGadget( struct Gadget *gadget, struct Window *window,
                         struct Requester *requester );

This function will fail if the user is in the middle of some other
interaction, such as menu or proportional gadget operation.  in that case
it returns FALSE, otherwise it returns TRUE. The window or requester
containing the string gadget to be activated must itself be open and
active.  Since some operations in Intuition may occur after the function
that initiates them completes, calling activategadget() after
openwindowtaglist() or request() is no guarantee that the gadget will
actually activate. Instead, call ActivateGadget() only after having
received an idcmp_activewindow or idcmp_reqset message for a newly opened
window or requester, respectively.

    The Window Active Message Is Required.
    --------------------------------------
    It is incorrect to simply insert a small delay between the call to
    openwindowtaglist() or request() and the call to activategadget().
    Such schemes fail under various conditions, including changes in
    processor speed and CPU loading.

If you want to activate a string gadget in a newly opened window that has
a shared IDCMP userport, there is an additional complication.  sharing
UserPorts means that the window is opened without any IDCMP messages
enabled, and only later is modifyidcmp() called to turn on message
passing.  If the newly opened window becomes active before ModifyIDCMP()
is called, the idcmp_activewindow message will not be received (because
IDCMP message passing was off at the time).  The following code will
handle this problem:

       BOOL activated;

       /* Open window with NULL IDCMPFlags */
       win = OpenWindow( ... );

       /* Set the UserPort to your shared port, and turn on message
        * passing, which includes the IDCMP_ACTIVEWINDOW message.
        */
       win->UserPort = sharedport;
       ModifyIDCMP( win, ... | IDCMP_ACTIVEWINDOW | ... );

       /* If the window became active before the ModifyIDCMP() got
        * executed, then this ActivateGadget() can succeed.  If not, then
        * this ActivateGadget() might be too early, but in that case, we
        * know we'll receive the IDCMP_ACTIVEWINDOW event.  We handle that
        * below.
        */
        activated = ActivateGadget( stringgad, win, NULL );

  and later, in the event loop:

    if ( (msg->Class == ACTIVEWINDOW) && ( !activated ) )
        success = ActivateGadget(stringgad,...);

Note however that a window which has the wa_activate attribute is not
guaranteed to be activated upon opening.  Certain conditions (like an
active string gadget in another window) will prevent the automatic initial
activation of the window.  Therefore, do not let your code depend on
receiving the initial idcmp_activewindow message.

 string gadget example