.\" Copyright (c) 2006-2022 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_FIXED 3
.Os Agar 1.7
.Sh NAME
.Nm AG_Fixed
.Nd agar fixed-position container widget
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
.\" IMAGE(/widgets/AG_Fixed.png, "Buttons, labels and pixmaps in an AG_Fixed")
The
.Nm
container widget positions and sizes its children at constant positions
specified in pixels.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_Widget 3 ->
.Nm .
.Sh INITIALIZATION
.nr nS 1
.Ft "AG_Fixed *"
.Fn AG_FixedNew "AG_Widget *parent" "Uint flags"
.Pp
.Ft void
.Fn AG_FixedSetStyle "AG_Fixed *fixed" "enum ag_fixed_style style"
.Pp
.Ft void
.Fn AG_FixedSizeHint "AG_Fixed *fixed" "int w" "int h"
.Pp
.nr nS 0
The
.Fn AG_FixedNew
function allocates, initializes, and attaches a new
.Nm
widget.
Accepted
.Fa flags
options include:
.Bl -tag -width "AG_FIXED_NO_UPDATE "
.It AG_FIXED_NO_UPDATE
Don't automatically call
.Xr AG_WidgetUpdate 3
whenever widgets are repositioned.
This allows the caller to, as an optimization use
.Xr AG_WidgetUpdate 3
only once after all widgets have been positioned.
.It AG_FIXED_HFILL
Expand horizontally in parent container.
.It AG_FIXED_VFILL
Expand vertically in parent container.
.It AG_FIXED_EXPAND
Shorthand for
.Dv AG_FIXED_HFILL | AG_FIXED_VFILL .
.El
.Pp
.Fn AG_FixedSetStyle
selects an alternate background and border style:
.Pp
.Bl -tag -compact -width "AG_FIXED_STYLE_PLAIN "
.It Dv AG_FIXED_STYLE_NONE
No background.
.It Dv AG_FIXED_STYLE_BOX
Raised box & border.
.It Dv AG_FIXED_STYLE_WELL
3D well & border (the default).
.It Dv AG_FIXED_STYLE_PLAIN
Filled rectangle.
.El
.Pp
Visible background styles use the style attributes "background-color",
"low-color" and "high-color".
.Pp
.Fn AG_FixedSizeHint
requests an initial size of
.Fa w
by
.Fa h
pixels.
.Sh CHILD WIDGETS
.nr nS 1
.Ft "void"
.Fn AG_FixedPut "AG_Fixed *fixed" "AG_Widget *child" "int x" "int y"
.Pp
.Ft "void"
.Fn AG_FixedDel "AG_Fixed *fixed" "AG_Widget *child"
.Pp
.Ft "void"
.Fn AG_FixedSize "AG_Fixed *fixed" "AG_Widget *child" "int width" "int height"
.Pp
.Ft "void"
.Fn AG_FixedMove "AG_Fixed *fixed" "AG_Widget *child" "int new_x" "int new_y"
.Pp
.nr nS 0
The
.Fn AG_FixedPut
function attaches the widget
.Fa child
and positions it at the given coordinates.
.Fn AG_FixedDel
detaches the given widget.
.Pp
Alternatively, you can avoid
.Fn AG_FixedPut
and
.Fn AG_FixedDel
altogether and instead use
.Xr AG_ObjectAttach 3
and
.Xr AG_ObjectDetach 3
followed by calls to
.Fn AG_FixedSize
and
.Fn AG_FixedMove .
.Pp
Functions
.Fn AG_FixedSize
and
.Fn AG_FixedMove
set the size and location of a given widget in pixels.
.Sh EVENTS
The
.Nm
widget does not generate any event.
.Sh STRUCTURE DATA
For the
.Ft AG_Fixed
object:
.Bl -tag -width "enum ag_fixed_style style "
.It Ft enum ag_fixed_style style
Background style (see
.Fn AG_FixedSetStyle ) .
.El
.Sh EXAMPLES
See
.Pa tests/fixedres.c
in the Agar source distribution.
.Sh SEE ALSO
.Xr AG_Box 3 ,
.Xr AG_Intro 3 ,
.Xr AG_MPane 3 ,
.Xr AG_Pane 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Sh HISTORY
The
.Nm
widget first appeared in Agar 1.0.
In Agar 1.6.0 the former
.Dv AG_FIXED_BOX ,
.Dv AG_FIXED_INVBOX ,
.Dv AG_FIXED_FRAME
and
.Dv AG_FIXED_FILLBG
flags were replaced by the
.Fn AG_FixedSetStyle
and the
.Va style
parameter.
.Fn AG_FixedSizeHint
appeared in Agar 1.6.0.