docs/latex/wx/helpinst.tex

   1 \section{\class{wxHelpInstance}}\label{wxhelpinstance}
   2
   3 NOTE: this documentation is out of date (see comments below).
   4
   5 The {\bf wxHelpInstance} class implements the interface by which
   6 applications may invoke wxHelp to provide on-line help. Each instance
   7 of the class maintains one connection to an instance of wxHelp which
   8 belongs to the application, and which is shut down when the Quit
   9 member of {\bf wxHelpInstance} is called (for example in the {\bf
  10 OnClose} member of an application's main frame). Under MS Windows,
  11 there is currently only one instance of wxHelp which is used by all
  12 applications.
  13
  14 Since there is a DDE link between the two programs, each subsequent
  15 request to display a file or section uses the existing instance of
  16 wxHelp, rather than starting a new instance each time. wxHelp thus
  17 appears to the user to be an extension of the current application.
  18 wxHelp may also be invoked independently of a client application.
  19
  20 Normally an application will create an instance of {\bf
  21 wxHelpInstance} when it starts, and immediately call {\bf Initialize}\rtfsp
  22 to associate a filename with it. wxHelp will only get run, however,
  23 just before the first call to display something. See the test program
  24 supplied with the wxHelp source.
  25
  26 Include the file {\tt wx\_help.h} to use this API, even if you have
  27 included {\tt wx.h}.
  28
  29 If you give TRUE to the constructor, you can use the native help system
  30 where appropriate (currently under Windows only). Omit the file extension
  31 to allow wxWindows to choose the appropriate file for the platform.
  32
  33 TODO: no longer derive this from a client class, but maybe have several implementations,
  34 e.g. wxHelpInstanceBase, wxHelpInstanceDDE, wxHelpInstanceWinHelp, wxHelpInstanceHTML, etc.
  35
  36 \wxheading{Derivation}
  37
  38 TODO
  39
  40 \wxheading{See also}
  41
  42 TODO
  43
  44 \latexignore{\rtfignore{\wxheading{Members}}}
  45
  46 \membersection{wxHelpInstance::wxHelpInstance}
  47
  48 \func{}{wxHelpInstance}{\param{bool}{ native}}
  49
  50 Constructs a help instance object, but does not invoke wxHelp.
  51 If {\it native} is TRUE, tries to use the native help system where
  52 possible (Windows Help under MS Windows, wxHelp on other platforms).
  53
  54 \membersection{wxHelpInstance::\destruct{wxHelpInstance}}
  55
  56 \func{}{\destruct{wxHelpInstance}}{\void}
  57
  58 Destroys the help instance, closing down wxHelp for this application
  59 if it is running.
  60
  61 \membersection{wxHelpInstance::Initialize}
  62
  63 \func{void}{Initialize}{\param{const wxString\& }{file}, \param{int}{ server = -1}}
  64
  65 Initializes the help instance with a help filename, and optionally a server (socket)
  66 number (one is chosen at random if this parameter is omitted). Does not invoke wxHelp.
  67 This must be called directly after the help instance object is created and before
  68 any attempts to communicate with wxHelp.
  69
  70 You may omit the file extension, and in fact this is recommended if you
  71 wish to support .xlp files under X and .hlp under Windows.
  72
  73 \membersection{wxHelpInstance::DisplayBlock}
  74
  75 \func{bool}{DisplayBlock}{\param{long}{ blockNo}}
  76
  77 If wxHelp is not running, runs wxHelp and displays the file at the given block number.
  78 If using Windows Help, displays the file at the given context number.
  79
  80 \membersection{wxHelpInstance::DisplayContents}
  81
  82 \func{bool}{DisplayContents}{\void}
  83
  84 If wxHelp is not running, runs wxHelp (or Windows Help) and displays the
  85 contents (the first section of the file).
  86
  87 \membersection{wxHelpInstance::DisplaySection}
  88
  89 \func{bool}{DisplaySection}{\param{int}{ sectionNo}}
  90
  91 If wxHelp is not running, runs wxHelp and displays the given section.
  92 Sections are numbered starting from 1, and section numbers may be viewed by running
  93 wxHelp in edit mode.
  94
  95 \membersection{wxHelpInstance::KeywordSearch}
  96
  97 \func{bool}{KeywordSearch}{\param{const wxString\& }{keyWord}}
  98
  99 If wxHelp (or Windows Help) is not running, runs wxHelp (or Windows
 100 Help), and searches for sections matching the given keyword. If one
 101 match is found, the file is displayed at this section. If more than one
 102 match is found, the Search dialog is displayed with the matches (wxHelp)
 103 or the first topic is displayed (Windows Help).
 104
 105 \membersection{wxHelpInstance::LoadFile}
 106
 107 \func{bool}{LoadFile}{\param{const wxString\& }{file = NULL}}
 108
 109 If wxHelp (or Windows Help) is not running, runs wxHelp (or Windows
 110 Help), and loads the given file. If the filename is not supplied or is
 111 NULL, the file specified in {\bf Initialize} is used. If wxHelp is
 112 already displaying the specified file, it will not be reloaded. This
 113 member function may be used before each display call in case the user
 114 has opened another file.
 115
 116 \membersection{wxHelpInstance::OnQuit}
 117
 118 \func{bool}{OnQuit}{\void}
 119
 120 Overridable member called when this application's wxHelp is quit
 121 (no effect if Windows Help is being used instead).
 122
 123 \membersection{wxHelpInstance::Quit}
 124
 125 \func{bool}{Quit}{\void}
 126
 127 If wxHelp is running, quits wxHelp by disconnecting (no effect for Windows
 128 Help).
 129
 130