1=head1 NAME
2
3UI::Dialog::Backend::XOSD - backend for the osd_cat(1).
4
5=head1 SYNOPSIS
6
7  use UI::Dialog::Backend::XOSD;
8  my $xosd = new UI::Dialog::Backend::XOSD ();
9  $xosd->line( text => "Something to display...");
10
11=head1 ABSTRACT
12
13UI::Dialog::Backend::XOSD is an OOPerl wrapper for the osd_cat(1)
14program.
15
16=head1 DESCRIPTION
17
18Use this module to present feedback to the end user via an on-screen
19display (like an on-screen TV volume meter).  When you use any of the
20UI::Dialog meta classes (UI::Dialog, UI::Dialog::GNOME, etc.) access
21to this backend is provided via the $d->xosd method. ie: replace $xosd
22with $d->xosd in the synopsis example (provided you made $d with
23something like my $d = new UI::Dialog...). Also, UI::Dialog (and
24friends) only load this module when you first use the $d->xosd method
25(this may silently fail, but you can test by ref() for success).
26
27=head1 EXPORT
28
29=over 2
30
31None
32
33=back
34
35=head1 INHERITS
36
37=over 2
38
39UI::Dialog::Backend
40
41=back
42
43=head1 CONSTRUCTOR
44
45=head2 new( @options )
46
47=over 4
48
49=item EXAMPLE
50
51=over 6
52
53 my $xosd = new UI::Dialog::Backend::XOSD ( );
54
55=back
56
57=item DESCRIPTION
58
59=over 6
60
61This is the Class Constructor method. It accepts a list of key => value pairs
62and uses them as the defaults when interacting with the various widgets. All
63methods accept the same arguments as new() except that the arguments passed to
64the methods are temporarily used instead of making them the default as the
65new() method does. In the case of the 'wait' option, any (non-zero) value enables
66the option as it's a switch and not a string argument.
67
68=back
69
70=item RETURNS
71
72=over 6
73
74A blessed object reference of the UI::Dialog::Backend::XOSD class.
75
76=back
77
78=item OPTIONS
79
80The (...)'s after each option indicate the default for the option. An * denotes
81support by all the widget methods on a per-use policy defaulting to the
82values decided during object creation.
83
84=over 6
85
86=item B<offset = \d+> (0) *
87
88=item B<align = \w+> ('left') *
89
90=item B<indent = \d+> (0) *
91
92=item B<font = "x-font-string"> ('fixed') *
93
94=item B<colour = \w+> ('red') *
95
96=item B<delay = \d+> (5) *
97
98=item B<lines = \d+> (5) *
99
100=item B<shadow = \d+> (0) *
101
102=item B<age = \d+> (0) *
103
104=item B<wait = 0,1> (0) *
105
106=back
107
108=back
109
110=head1 METHODS
111
112=head2 line( )
113
114=over 4
115
116=item EXAMPLE
117
118=over 6
119
120 $xosd->line( text => "some text to display" );
121
122=back
123
124=item DESCRIPTION
125
126=over 6
127
128Display a simple string on the screen.
129
130=back
131
132=item RETURNS
133
134=over 6
135
136Nothing.
137
138=back
139
140=back
141
142=head2 file( )
143
144=over 4
145
146=item EXAMPLE
147
148=over 6
149
150 $xosd->file( file => "/path/to/a/file" );
151
152=back
153
154=item DESCRIPTION
155
156=over 6
157
158Display a file on the screen.
159
160=back
161
162=item RETURNS
163
164=over 6
165
166Nothing.
167
168=back
169
170=back
171
172=head2 gauge( )
173
174=over 4
175
176=item EXAMPLE
177
178=over 6
179
180 $xosd->gauge( text => "",
181               percent => $current_percentage,
182               length => 40,
183               bar => "-",
184               mark => "|" );
185
186=back
187
188=item DESCRIPTION
189
190=over 6
191
192Display a gauge bar with a percentage mark on the screen with an optional
193message.
194
195=back
196
197=item RETURNS
198
199=over 6
200
201Nothing.
202
203=back
204
205=back
206
207=head2 display_start( )
208
209=over 4
210
211=item EXAMPLE
212
213=over 6
214
215 $xosd->display_start( );
216
217=back
218
219=item DESCRIPTION
220
221=over 6
222
223Opens a pipe command to the osd_cat(1) program for prolonged interactivity.
224This accepts all of the standard options but has nothing else to offer. The
225other display_*() methods (detailed below) return zero unless this method has
226been used and has created the command pipe.
227
228=back
229
230=item RETURNS
231
232=over 6
233
234TRUE (1) for success and FALSE (0) otherwise.
235
236=back
237
238=back
239
240=head2 display_text( )
241
242=over 4
243
244=item EXAMPLE
245
246=over 6
247
248 $xosd->display_start();
249 $xosd->display_text( "Some string to display." );
250
251=back
252
253=item DESCRIPTION
254
255=over 6
256
257Uses the command pipe created by display_start() and prints the first argument
258to the screen. This method does not have any options, save the one string
259scalar.
260
261=back
262
263=item RETURNS
264
265=over 6
266
267TRUE (1) for success and FALSE (0) otherwise.
268
269=back
270
271=back
272
273=head2 display_gauge( )
274
275=over 4
276
277=item EXAMPLE
278
279=over 6
280
281 $xosd->display_start();
282 $xosd->display_gauge( 50, "display an optional text string." );
283
284=back
285
286=item DESCRIPTION
287
288=over 6
289
290Uses the command pipe created by display_start() and prints a gauge identical
291to the regular (stand-alone) gauge() method. There are only to accepted
292arguments; the desired percentage and an optional text string.
293
294=back
295
296=item RETURNS
297
298=over 6
299
300TRUE (1) for success and FALSE (0) otherwise.
301
302=back
303
304=back
305
306=head2 display_stop( )
307
308=over 4
309
310=item EXAMPLE
311
312=over 6
313
314 $xosd->display_start();
315 $xosd->display_text( "about to stop!" );
316 $xosd->display_stop();
317
318=back
319
320=item DESCRIPTION
321
322=over 6
323
324This closes the command pipe opened by the display_start() method. This method
325takes no arguments and performs only the task for closing and existing
326command pipe.
327
328=back
329
330=item RETURNS
331
332=over 6
333
334TRUE (1) for success and FALSE (0) otherwise.
335
336=back
337
338=back
339
340=head1 SEE ALSO
341
342=over 2
343
344=item PERLDOC
345
346 UI::Dialog
347 UI::Dialog::Backend
348
349=back
350
351=over 2
352
353=item MAN FILES
354
355osd_cat(1)
356
357=back
358
359=head1 BUGS
360
361Please email the author with any bug reports. Include the name of the
362module in the subject line.
363
364=head1 AUTHOR
365
366Kevin C. Krinke, E<lt>kevin@krinke.caE<gt>
367
368=head1 COPYRIGHT AND LICENSE
369
370 Copyright (C) 2004-2016  Kevin C. Krinke <kevin@krinke.ca>
371
372 This library is free software; you can redistribute it and/or
373 modify it under the terms of the GNU Lesser General Public
374 License as published by the Free Software Foundation; either
375 version 2.1 of the License, or (at your option) any later version.
376
377 This library is distributed in the hope that it will be useful,
378 but WITHOUT ANY WARRANTY; without even the implied warranty of
379 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
380 Lesser General Public License for more details.
381
382 You should have received a copy of the GNU Lesser General Public
383 License along with this library; if not, write to the Free Software
384 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
385
386=cut
387