VkRunOnce(3x)

NAME
     VkRunOnce - Allow an application to have only a single instance

INHERITS FROM
     VkComponent : VkCallbackObject

HEADER FILE
     #include <Vk/VkRunOnce.h>


PUBLIC PROTOCOL SUMMARY
   Constructor/Destructor
           VkRunOnce(VkNameList *args, Boolean per_host);
           ~VkRunOnce();


   Retrieving Arguments
           int numArgs();
           char *arg(int index);


   Callbacks
           const char *const invokedCallback;


CLASS DESCRIPTION
     This class is subtly different from VkRunOnce2.  Both classes should be
     understood before deciding which to use.

     This class allows applications to specify that only a single instance of
     the application can be run on any system at any one time. This is useful
     when implementing applications that are meant to provide a system-wide
     service for multiple applications. For example, an audio control program
     that controls the volume an other parameters on a system should not
     normally need to have multiple instantiations. However, various programs
     or scripts might wish to launch the application, and have no way to know
     if the program is already running.

     Using VkRunOnce, such programs can simply be run as many times as
     desired.  Only the first run will actually display the program.
     Subsequent runs will notify the running instance, possibly passing some
     arguments. The running instance will raise itself, and respond to any
     arguments provided. The second instance of the application will simply
     exit.

FUNCTION DESCRIPTIONS
   VkRunOnce
            VkRunOnce(VkNameList *args,
                       Boolean per_host);

          Initialize a VkRunOnce object. If this is the only current instance
          of this program running on the system, this constructor establishes
          this application as the sole runnable instance. Normally, "running
          on this system" is defined to mean an application whose X DISPLAY is
          set to the current display device. If per_host is TRUE, multiple
          instances are allowed on any given display, so long as each instance
          is running on a different host.

          If this is the second time an application is run, the VkRunOnce
          constructor makes contact with the running instance, passing it any
          arguments supplied in the args parameter. The constructor then
          causes the application to exit by calling VkApp::terminate().

   ~VkRunOnce
              ~VkRunOnce();


          If the VkRunOnce object is deleted, and this application is the
          current single instance of this application, multiple instances of
          this program are then allowed to run.

   className
              virtual const char* className();


          The class name of this class is "VkRunOnce".

EXAMPLES
     The following program displays a string in a window. After the first
     instance, subsequent instances of the program pass the first command line
     argument to the running instance, to be displayed as a string in the
     application's window.


           #include <Vk/VkApp.h>
           #include <Vk/VkRunOnce.h>
           #include <Vk/VkNameList.h>
           #include <Vk/VkSimpleWindow.h>
           #include <Xm/Label.h>

           // Define a top-level window class

           class RunOnceWindow: public VkSimpleWindow {

            protected:

               Widget _label;


            public:

              RunOnceWindow ( const char *name ) :
                           VkSimpleWindow ( name )
              {
                   _label =  XmCreateLabel ( mainWindowWidget(),
                                             "first instance",
                                              NULL, 0 );

                   addView(_label);
              }

              ~RunOnceWindow();

              void update(VkComponent *comp, XtPointer, XtPointer);

              virtual const char* className() {
                                 return "RunOnceWindow";
                              }
           };

           RunOnceWindow::~RunOnceWindow()
           {
              // Empty
           }

           void RunOnceWindow::update(VkComponent *comp,
                                      void*,
                                      void*)
           {
              // Just retrieve the arguments, Use the first string
              // as a new label for the widget and the second
              // as a color.

              VkRunOnce *obj = (VkRunOnce*) comp;

              if(obj->numArgs() > 0)
              {
                  XtVaSetValues(_label,
                                XtVaTypedArg,
                                XmNlabelString, XmRString,
                                obj->arg(0),
                                strlen(obj->arg(0) ) + 1,
                                NULL);
              }
           }


           // Main driver. Instantiate a VkApp and a top-level
           // window, "show" the window and then "run" the
           // application. The VkRunOnce object prevents
           // multiple instances of the application.

           void main ( int argc, char **argv )
           {
              VkApp        *app = new VkApp("RunOnce", &argc, argv);

              // Construct a VkNameList object to pass arguments
              // and load the first argument, if any

              VkNameList *args = new VkNameList();

              if(argc == 2)
                  args->add(argv[1]);

              VkRunOnce *runOnce = new VkRunOnce(args);

              // Create a window

              RunOnceWindow  *win = new RunOnceWindow("hello");

              // Register a callback for running applications
              // to receive if anyone attempts to run this
              // application again.

              VkAddCallbackMethod(VkRunOnce::invokedCallback, runOnce,
                                  win, RunOnceWindow::update, NULL);

              win->show();
              app->run();
           }



INHERITED MEMBER FUNCTIONS
   Inherited from VkComponent
          installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(),
          setDefaultResources(), getResources(), manage(), unmanage(),
          baseWidget(), okToQuit(), _name, _baseWidget, _w, deleteCallback


   Inherited from VkCallbackObject
          callCallbacks(), addCallback(), removeCallback(),
          removeAllCallbacks()


SEE ALSO
     VkApp(3x), VkRunOnce2(3)
     ViewKit Programmer's Guide
     The X Window System, DEC Press, Bob Sheifler and Jim Gettys
     The X Window System Toolkit, DEC Press, Paul Asente and Ralph Swick
     The OSF/Motif Programmers Reference, Prentice Hall, OSF