annotate scripts/gui/uipushtool.m @ 30875:5d3faba0342e

doc: Ensure documentation lists output argument when it exists for all m-files. For new users of Octave it is best to show explicit calling forms in the documentation and to show a return argument when it exists. * bp-table.cc, shift.m, accumarray.m, accumdim.m, bincoeff.m, bitcmp.m, bitget.m, bitset.m, blkdiag.m, celldisp.m, cplxpair.m, dblquad.m, flip.m, fliplr.m, flipud.m, idivide.m, int2str.m, interpft.m, logspace.m, num2str.m, polyarea.m, postpad.m, prepad.m, randi.m, repmat.m, rng.m, rot90.m, rotdim.m, structfun.m, triplequad.m, uibuttongroup.m, uicontrol.m, uipanel.m, uipushtool.m, uitoggletool.m, uitoolbar.m, waitforbuttonpress.m, help.m, __additional_help_message__.m, hsv.m, im2double.m, im2frame.m, javachk.m, usejava.m, argnames.m, char.m, formula.m, inline.m, __vectorize__.m, findstr.m, flipdim.m, strmatch.m, vectorize.m, commutation_matrix.m, cond.m, cross.m, duplication_matrix.m, expm.m, orth.m, rank.m, rref.m, trace.m, vech.m, cast.m, compare_versions.m, delete.m, dir.m, fileattrib.m, grabcode.m, gunzip.m, inputname.m, license.m, list_primes.m, ls.m, mexext.m, movefile.m, namelengthmax.m, nargoutchk.m, nthargout.m, substruct.m, swapbytes.m, ver.m, verLessThan.m, what.m, fminunc.m, fsolve.m, fzero.m, optimget.m, __fdjac__.m, matlabroot.m, savepath.m, campos.m, camroll.m, camtarget.m, camup.m, camva.m, camzoom.m, clabel.m, diffuse.m, legend.m, orient.m, rticks.m, specular.m, thetaticks.m, xlim.m, xtickangle.m, xticklabels.m, xticks.m, ylim.m, ytickangle.m, yticklabels.m, yticks.m, zlim.m, ztickangle.m, zticklabels.m, zticks.m, ellipsoid.m, isocolors.m, isonormals.m, stairs.m, surfnorm.m, __actual_axis_position__.m, __pltopt__.m, close.m, graphics_toolkit.m, pan.m, print.m, printd.m, __ghostscript__.m, __gnuplot_print__.m, __opengl_print__.m, rotate3d.m, subplot.m, zoom.m, compan.m, conv.m, poly.m, polyaffine.m, polyder.m, polyint.m, polyout.m, polyreduce.m, polyvalm.m, roots.m, prefdir.m, prefsfile.m, profexplore.m, profexport.m, profshow.m, powerset.m, unique.m, arch_rnd.m, arma_rnd.m, autoreg_matrix.m, bartlett.m, blackman.m, detrend.m, durbinlevinson.m, fftconv.m, fftfilt.m, fftshift.m, fractdiff.m, hamming.m, hanning.m, hurst.m, ifftshift.m, rectangle_lw.m, rectangle_sw.m, triangle_lw.m, sinc.m, sinetone.m, sinewave.m, spectral_adf.m, spectral_xdf.m, spencer.m, ilu.m, __sprand__.m, sprand.m, sprandn.m, sprandsym.m, treelayout.m, beta.m, betainc.m, betaincinv.m, betaln.m, cosint.m, expint.m, factorial.m, gammainc.m, gammaincinv.m, lcm.m, nthroot.m, perms.m, reallog.m, realpow.m, realsqrt.m, sinint.m, hadamard.m, hankel.m, hilb.m, invhilb.m, magic.m, pascal.m, rosser.m, toeplitz.m, vander.m, wilkinson.m, center.m, corr.m, cov.m, discrete_cdf.m, discrete_inv.m, discrete_pdf.m, discrete_rnd.m, empirical_cdf.m, empirical_inv.m, empirical_pdf.m, empirical_rnd.m, kendall.m, kurtosis.m, mad.m, mean.m, meansq.m, median.m, mode.m, moment.m, range.m, ranks.m, run_count.m, skewness.m, spearman.m, statistics.m, std.m, base2dec.m, bin2dec.m, blanks.m, cstrcat.m, deblank.m, dec2base.m, dec2bin.m, dec2hex.m, hex2dec.m, index.m, regexptranslate.m, rindex.m, strcat.m, strjust.m, strtrim.m, strtrunc.m, substr.m, untabify.m, __have_feature__.m, __prog_output_assert__.m, __run_test_suite__.m, example.m, fail.m, asctime.m, calendar.m, ctime.m, date.m, etime.m: Add return arguments to @deftypefn macros where they were missing. Rename variables in functions (particularly generic "retval") to match documentation. Rename some return variables for (hopefully) better clarity (e.g., 'ax' to 'hax' to indicate it is a graphics handle to an axes object).
author Rik <rik@octave.org>
date Wed, 30 Mar 2022 20:40:27 -0700
parents 796f54d4ddbf
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
1 ########################################################################
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
2 ##
30564
796f54d4ddbf update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 29358
diff changeset
3 ## Copyright (C) 2012-2022 The Octave Project Developers
27918
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26877
diff changeset
4 ##
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
5 ## See the file COPYRIGHT.md in the top-level directory of this
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
6 ## distribution or <https://octave.org/copyright/>.
13703
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
7 ##
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
8 ## This file is part of Octave.
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
9 ##
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23567
diff changeset
10 ## Octave is free software: you can redistribute it and/or modify it
13703
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
11 ## under the terms of the GNU General Public License as published by
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23567
diff changeset
12 ## the Free Software Foundation, either version 3 of the License, or
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
13 ## (at your option) any later version.
13703
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
14 ##
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
15 ## Octave is distributed in the hope that it will be useful, but
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
16 ## WITHOUT ANY WARRANTY; without even the implied warranty of
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
17 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
18 ## GNU General Public License for more details.
13703
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
19 ##
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
20 ## You should have received a copy of the GNU General Public License
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
21 ## along with Octave; see the file COPYING. If not, see
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23567
diff changeset
22 ## <https://www.gnu.org/licenses/>.
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
23 ##
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
24 ########################################################################
13703
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
25
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
26 ## -*- texinfo -*-
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
27 ## @deftypefn {} {} uipushtool ()
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
28 ## @deftypefnx {} {} uipushtool (@var{property}, @var{value}, @dots{})
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
29 ## @deftypefnx {} {} uipushtool (@var{parent})
23271
cc9dcadcef6b Only return a handle from ui* functions if nargout > 0 (bug #49751).
Rik <rik@octave.org>
parents: 23220
diff changeset
30 ## @deftypefnx {} {} uipushtool (@var{parent}, @var{property}, @var{value}, @dots{})
20597
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
31 ##
23271
cc9dcadcef6b Only return a handle from ui* functions if nargout > 0 (bug #49751).
Rik <rik@octave.org>
parents: 23220
diff changeset
32 ## Create a uipushtool object.
20597
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
33 ##
20716
1ecee53513d7 doc: Peridodic grammar check of documentation.
Rik <rik@octave.org>
parents: 20715
diff changeset
34 ## uipushtools are buttons that appear on a figure toolbar. The button is
20768
7655b399abff eliminate trailing whitespace in source files we maintain
John W. Eaton <jwe@octave.org>
parents: 20719
diff changeset
35 ## created with a border that is shown when the user hovers over the button.
20716
1ecee53513d7 doc: Peridodic grammar check of documentation.
Rik <rik@octave.org>
parents: 20715
diff changeset
36 ## An image can be set using the cdata property.
20597
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
37 ##
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
38 ## If @var{parent} is omitted then a uipushtool for the current figure is
20716
1ecee53513d7 doc: Peridodic grammar check of documentation.
Rik <rik@octave.org>
parents: 20715
diff changeset
39 ## created. If no figure is available, a new figure is created first. If a
1ecee53513d7 doc: Peridodic grammar check of documentation.
Rik <rik@octave.org>
parents: 20715
diff changeset
40 ## figure is available, but does not contain a uitoolbar, a uitoolbar will be
1ecee53513d7 doc: Peridodic grammar check of documentation.
Rik <rik@octave.org>
parents: 20715
diff changeset
41 ## created.
20597
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
42 ##
23567
71bfd507663c doc: Periodic spellcheck of documentation.
Rik <rik@octave.org>
parents: 23396
diff changeset
43 ## If @var{parent} is given then a uipushtool is created on the @var{parent}
71bfd507663c doc: Periodic spellcheck of documentation.
Rik <rik@octave.org>
parents: 23396
diff changeset
44 ## uitoolbar.
20715
5b7643257978 Remove trailing whitespace at end of lines.
Rik <rik@octave.org>
parents: 20615
diff changeset
45 ##
20716
1ecee53513d7 doc: Peridodic grammar check of documentation.
Rik <rik@octave.org>
parents: 20715
diff changeset
46 ## Any provided property value pairs will override the default values of the
1ecee53513d7 doc: Peridodic grammar check of documentation.
Rik <rik@octave.org>
parents: 20715
diff changeset
47 ## created uipushtool object.
20597
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
48 ##
26877
83774c2a1b92 doc: Place cross-reference from list of graphics object properties back to object (bug #46076).
Rik <rik@octave.org>
parents: 26376
diff changeset
49 ## The full list of properties is documented at @ref{Uipushtool Properties}.
20615
93d96da9ff3e Update uiXXXXX documentation for autogenerated properties
John Donoghue
parents: 20597
diff changeset
50 ##
23271
cc9dcadcef6b Only return a handle from ui* functions if nargout > 0 (bug #49751).
Rik <rik@octave.org>
parents: 23220
diff changeset
51 ## The optional return value @var{hui} is a graphics handle to the created
23567
71bfd507663c doc: Periodic spellcheck of documentation.
Rik <rik@octave.org>
parents: 23396
diff changeset
52 ## uipushtool object.
23271
cc9dcadcef6b Only return a handle from ui* functions if nargout > 0 (bug #49751).
Rik <rik@octave.org>
parents: 23220
diff changeset
53 ##
20597
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
54 ## Examples:
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
55 ##
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
56 ## @example
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
57 ## @group
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
58 ## % create figure without a default toolbar
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
59 ## f = figure ("toolbar", "none");
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
60 ## % create empty toolbar
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
61 ## t = uitoolbar (f);
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
62 ## % create a 19x19x3 black square
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
63 ## img=zeros(19,19,3);
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
64 ## % add pushtool button to toolbar
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
65 ## b = uipushtool (t, "cdata", img);
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
66 ## @end group
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
67 ## @end example
7890893a0e69 Add uiXXXX documentation (Bug #46076)
John Donoghue <john.donoghue@ieee.org>
parents: 19833
diff changeset
68 ## @seealso{figure, uitoolbar, uitoggletool}
13703
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
69 ## @end deftypefn
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
70
19833
9fc020886ae9 maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents: 19697
diff changeset
71 function hui = uipushtool (varargin)
13703
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
72
19833
9fc020886ae9 maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents: 19697
diff changeset
73 [h, args] = __uiobject_split_args__ ("uipushtool", varargin,
9fc020886ae9 maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents: 19697
diff changeset
74 {"uitoolbar"}, 0);
13703
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
75 if (isempty (h))
13726
5a2734f26dbc Create uitoolbar only when necessary.
Michael Goffioul <michael.goffioul@gmail.com>
parents: 13703
diff changeset
76 h = findobj (gcf, "-depth", 1, "type", "uitoolbar");
5a2734f26dbc Create uitoolbar only when necessary.
Michael Goffioul <michael.goffioul@gmail.com>
parents: 13703
diff changeset
77 if (isempty (h))
5a2734f26dbc Create uitoolbar only when necessary.
Michael Goffioul <michael.goffioul@gmail.com>
parents: 13703
diff changeset
78 h = uitoolbar ();
5a2734f26dbc Create uitoolbar only when necessary.
Michael Goffioul <michael.goffioul@gmail.com>
parents: 13703
diff changeset
79 else
5a2734f26dbc Create uitoolbar only when necessary.
Michael Goffioul <michael.goffioul@gmail.com>
parents: 13703
diff changeset
80 h = h(1);
5a2734f26dbc Create uitoolbar only when necessary.
Michael Goffioul <michael.goffioul@gmail.com>
parents: 13703
diff changeset
81 endif
13703
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
82 endif
23396
945b53af4655 maint: Strip trailing whitespace from source files.
John W. Eaton <jwe@octave.org>
parents: 23271
diff changeset
83
23271
cc9dcadcef6b Only return a handle from ui* functions if nargout > 0 (bug #49751).
Rik <rik@octave.org>
parents: 23220
diff changeset
84 htmp = __go_uipushtool__ (h, args{:});
23396
945b53af4655 maint: Strip trailing whitespace from source files.
John W. Eaton <jwe@octave.org>
parents: 23271
diff changeset
85
23271
cc9dcadcef6b Only return a handle from ui* functions if nargout > 0 (bug #49751).
Rik <rik@octave.org>
parents: 23220
diff changeset
86 if (nargout > 0)
cc9dcadcef6b Only return a handle from ui* functions if nargout > 0 (bug #49751).
Rik <rik@octave.org>
parents: 23220
diff changeset
87 hui = htmp;
cc9dcadcef6b Only return a handle from ui* functions if nargout > 0 (bug #49751).
Rik <rik@octave.org>
parents: 23220
diff changeset
88 endif
13703
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
89
22ce748da25f Add missing UI objects: uicontextmenu, uitoolbar, uipushtool and uitoggletool.
Michael Goffioul <michael.goffioul@gmail.com>
parents:
diff changeset
90 endfunction