.\" Copyright (c) 2003-2023 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd December 21, 2022
.Dt AG_NUMERICAL 3
.Os Agar 1.7
.Sh NAME
.Nm AG_Numerical
.Nd agar numerical editor widget
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
.\" IMAGE(/widgets/AG_Numerical.png, "A numerical widget bound to a distance value")
The
.Nm
widget allows the value of an integer or floating-point variable to be
edited by the user.
.Nm
provides a
.Va value
binding, and optional limits may be specified as the
.Va min
and
.Va max
bindings.
.Pp
If
.Va min
or
.Va max
are undefined when the widget is first shown, default limits are
set according to the widest numerical range that can be represented by
the type of
.Va value .
.Pp
.Nm
is composed of an
.Xr AG_Textbox 3
with two vertically-stacked
.Xr AG_Button 3
to increment and decrement the value and an
.Xr AG_UCombo 3
based unit selector (optional).
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_Widget 3 ->
.Nm .
.Sh INITIALIZATION
.nr nS 1
.Ft "AG_Numerical *"
.Fn AG_NumericalNew "AG_Widget *parent" "Uint flags" "const char *unit" "const char *format" "..."
.Pp
.Ft "AG_Numerical *"
.Fn AG_NumericalNewS "AG_Widget *parent" "Uint flags" "const char *unit" "const char *label"
.Pp
.\" MANLINK(AG_NumericalNewFlt)
.\" MANLINK(AG_NumericalNewDbl)
.\" MANLINK(AG_NumericalNewLdbl)
.\" MANLINK(AG_NumericalNewInt)
.\" MANLINK(AG_NumericalNewUint)
.Ft "AG_Numerical *"
.Fn AG_NumericalNew{Flt,Dbl,Ldbl,Int,Uint} "AG_Widget *parent" "Uint flags" "const char *unit" "const char *label" "<Type> *value"
.Pp
.\" MANLINK(AG_NumericalNewFltR)
.\" MANLINK(AG_NumericalNewDblR)
.\" MANLINK(AG_NumericalNewLdblR)
.\" MANLINK(AG_NumericalNewIntR)
.\" MANLINK(AG_NumericalNewUintR)
.Ft "AG_Numerical *"
.Fn AG_NumericalNew{Flt,Dbl,Ldbl,Int,Uint}R "AG_Widget *parent" "Uint flags" "const char *unit" "const char *label" "<Type> *value" "<Type> min" "<Type> max"
.Pp
.Ft "void"
.Fn AG_NumericalSizeHint "AG_Numerical *num" "const char *sizeHint"
.Pp
.Ft int
.Fn AG_NumericalSetUnitSystem "AG_Numerical *num" "const char *unit"
.Pp
.Ft void
.Fn AG_NumericalSelectUnit "AG_Numerical *num" "const char *unit"
.Pp
.Ft void
.Fn AG_NumericalSetPrecision "AG_Numerical *num" "const char *fmt" "int precision"
.Pp
.Ft void
.Fn AG_NumericalSetWriteable "AG_Numerical *num" "int writeable"
.Pp
.nr nS 0
The
.Fn AG_NumericalNew
function allocates, initializes, and attaches a new
.Nm
widget.
Acceptable
.Fa flags
include:
.Bl -tag -width "AG_NUMERICAL_NO_POS_INF "
.It AG_NUMERICAL_INT
If no "value" binding has been set when the widget is first shown,
use a built-in variable of type
.Ft int
(by default,
.Ft double
is used).
.It AG_NUMERICAL_EXCL
No external changes to the
.Va value
binding are to be expected.
This allows
.Nm
to optimize based on exclusive access (by default, the value is checked periodically and the widget is redrawn
if a change is detected).
.It AG_NUMERICAL_SLOW
In non-EXCL case, check value every 2 seconds instead of the default
of 250ms.
.It AG_NUMERICAL_NO_POS_INF
Don't allow "inf" (or U+221E) float input.
.It AG_NUMERICAL_NO_POS_INF
Don't allow "-inf" (or "-" U+221E) float input
.It AG_NUMERICAL_NO_INF
Shorthand for
.Dv AG_NUMERICAL_NO_POS_INF | AG_NUMERICAL_NO_NEG_INF .
.It AG_NUMERICAL_HFILL
Expand horizontally in parent container.
.It AG_NUMERICAL_VFILL
Expand vertically in parent container.
.It AG_NUMERICAL_EXPAND
Shorthand for
.Dv AG_NUMERICAL_HFILL | AG_NUMERICAL_VFILL .
.El
.Pp
The
.Fa unit
argument is the name of the conversion unit that will be used by default
(other conversion units in the same unit group will also be displayed in the
unit selector).
If
.Fa unit
is NULL, no conversion is done and the unit selector is not shown.
See
.Xr AG_Units 3
for more information.
.Pp
The alternate constructor routines
.Fn AG_NumericalNew<Type>
create a new widget bound to a variable of the specified type.
.Fn AG_NumericalNew<Type>R
also accept explicit
.Fa min
and
.Fa max
arguments.
.Pp
.Fn AG_NumericalSizeHint
requests that the initial geometry of the
.Nm
widget be sufficient to display
.Fa sizeHint
in its entirety (see
.Xr AG_SizeSpec 3 ) .
.Pp
.Fn AG_NumericalSetUnitSystem
searches all unit groups for a unit of the given name and selects it as the
active unit.
Other units in the group will be displayed in the unit selector.
If no such unit exists, the function returns -1.
.Pp
.Fn AG_NumericalSelectUnit
searches only the current unit group and selects the unit of the given name
as the active conversion unit.
.Pp
The
.Fn AG_NumericalSetPrecision
function selects the preferred style and precision for printing floating-point
numbers.
The default is
.Sq %.2f .
.Pp
.Fn AG_NumericalSetWriteable
enables of disables user modification
sets the writeability flag, also accessible as the
.Va writeable
member of the structure.
.Sh NUMERICAL OPERATIONS
.nr nS 1
.Ft void
.Fn AG_NumericalIncrement "AG_Numerical *num"
.Pp
.Ft void
.Fn AG_NumericalDecrement "AG_Numerical *num"
.Pp
.Ft "float"
.Fn AG_NumericalGetFlt "AG_Numerical *num"
.Pp
.Ft "double"
.Fn AG_NumericalGetDbl "AG_Numerical *num"
.Pp
.nr nS 0
The
.Fn AG_NumericalIncrement
and
.Fn AG_NumericalDecrement
functions increment and decrement the bound
.Va value
by the interval specified as the
.Va inc
binding (which defaults to 1).
.Pp
.Fn AG_NumericalGetFlt ,
.Fn AG_NumericalGetDbl
and
.Fn AG_NumericalGetLdbl
return a representation of the current numerical value.
.Sh STRUCTURE DATA
For the
.Ft AG_Numerical
object:
.Pp
.Bl -tag -compact -width "const AG_Unit *unit "
.It Ft char *format
Format string for printing floating-point numbers.
.It Ft const AG_Unit *unit
Current unit system in use.
.It Ft AG_Textbox *input
Textbox for keyboard input.
.El
.Sh EVENTS
The
.Nm
widget generates the following events:
.Pp
.Bl -tag -compact -width 2n
.It Fn numerical-changed "void"
The value has been modified by the textbox or the +/- buttons.
.It Fn numerical-return "void"
The value has been modified by the textbox and return was pressed.
.El
.Sh BINDINGS
The
.Nm
widget provides the following bindings:
.Pp
.Bl -tag -compact -width "double *value, *min, *max, *inc "
.It Va float *value, *min, *max, *inc
Real number (single-precision).
.It Va double *value, *min, *max, *inc
Real number (double-precision).
.It Va int *value, *min, *max, *inc
Signed integer value.
.It Va Uint *value, *min, *max, *inc
Unsigned integer value.
.It Va Uint8 *value, *min, *max, *inc
Unsigned 8-bit value.
.It Va Uint16 *value, *min, *max, *inc
Unsigned 16-bit value.
.It Va Uint32 *value, *min, *max, *inc
Unsigned 32-bit value.
.It Va Uint64 *value, *min, *max, *inc
Unsigned 64-bit value.
.It Va Sint8 *value, *min, *max, *inc
Signed 8-bit value.
.It Va Sint16 *value, *min, *max, *inc
Signed 16-bit value.
.It Va Sint32 *value, *min, *max, *inc
Signed 32-bit value.
.It Va Sint64 *value, *min, *max, *inc
Signed 64-bit value.
.El
.Pp
The
.Va value
binding indicates the number to display.
The
.Va min
and
.Va max
bindings allow a range to be specified.
The
.Va inc
binding specifies the increment effected by the widget's "+" and "-" buttons
(if unit conversion is in use,
.Va inc
should be of the same unit system as
.Va value ) .
.Pp
The 64-bit types are only available if
.Dv AG_HAVE_64BIT
is defined.
.Sh SEE ALSO
.Xr AG_Button 3 ,
.Xr AG_Intro 3 ,
.Xr AG_Textbox 3 ,
.Xr AG_Ucombo 3 ,
.Xr AG_Units 3
.Sh HISTORY
The
.Nm
widget first appeared in Agar 1.2 as a replacement for
.Sq AG_Spinbutton
and
.Sq AG_FSpinbutton
that can handle both floating-point and integer values.
Agar 1.5 added support for 64-bit types.