VkRunOnce(3x)VkRunOnce(3x)NAMEVkRunOnce - 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 DESCRIPTIONSVkRunOnce
VkRunOnce(VkNameList *args,
Boolean per_host);
Page 1
VkRunOnce(3x)VkRunOnce(3x)
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 ) :
Page 2
VkRunOnce(3x)VkRunOnce(3x)
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 )
{
Page 3
VkRunOnce(3x)VkRunOnce(3x)
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 ALSOVkApp(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
Page 4
