<!-- $XConsortium: FontLstP.sgm /main/8 1996/09/08 20:44:16 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->

<RefEntry Id="CDEMMA.MAN236.rsml.1">
<RefMeta>
<RefEntryTitle>XmFontListEntryLoad</RefEntryTitle>
<ManVolNum>library call</ManVolNum>
</RefMeta>
<RefNameDiv>
<RefName><Function>XmFontListEntryLoad</Function></RefName>
<RefPurpose>A font list function that loads
a font or creates a font set and creates an accompanying font list entry
<IndexTerm>
<Primary>XmFontListEntryLoad</Primary>
</IndexTerm><IndexTerm>
<Primary>font list functions</Primary>
<Secondary>XmFontListEntryLoad</Secondary>
</IndexTerm></RefPurpose>
</RefNameDiv>
<!-- -->
<!-- @OSF_COPYRIGHT@-->
<!-- COPYRIGHT NOTICE-->
<!-- Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc.-->
<!-- ALL RIGHTS RESERVED (MOTIF). See the file named COPY.MOTIF.DOC for-->
<!-- the full copyright text.-->
<!-- -->
<!-- HISTORY-->
<!-- -->
<!-- **-->
<!-- **-->
<!-- **  (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc.-->
<!-- **      All Rights Reserved.-->
<!-- **-->
<!-- **  (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company-->
<!-- **-->
<!-- **  (c) Copyright 1987, 1988 by Digital Equipment Corporation,-->
<!-- **      Maynard, MA.  All Rights Reserved.-->
<!-- **-->
<!-- **-->
<RefSynopsisDiv>
<FuncSynopsis>
<FuncSynopsisInfo>#include &lt;Xm/Xm.h>
</FuncSynopsisInfo>
<FuncDef>XmFontListEntry <Function>XmFontListEntryLoad</Function></FuncDef>
<!--<ParamDef><Replaceable>display, font_name, type, tag</Replaceable></ParamDef>-->
<ParamDef>Display *<Parameter>display</Parameter></ParamDef>
<ParamDef>char *<Parameter>font_name</Parameter></ParamDef>
<ParamDef>XmFontType <Parameter>type</Parameter></ParamDef>
<ParamDef>char *<Parameter>tag</Parameter></ParamDef>
</FuncSynopsis>
</RefSynopsisDiv>
<RefSect1>
<Title>DESCRIPTION</Title>
<Para><Function>XmFontListEntryLoad</Function> loads a font or creates a font set
based on the value of the <Symbol Role="Variable">type</Symbol> argument. It creates and returns
a font list entry that contains the font or font set and the
specified tag.
</Para>
<Para>If the value of <Symbol Role="Variable">type</Symbol> is <SystemItem Class="Constant">XmFONT_IS_FONT</SystemItem>, the function uses
the <Function>XtCvtStringToFontStruct</Function> routine to convert the value of
<Symbol Role="Variable">font_name</Symbol> to a font struct.
If the value of <Symbol Role="Variable">type</Symbol> is <SystemItem Class="Constant">XmFONT_IS_FONTSET</SystemItem>, the function uses
the <Function>XtCvtStringToFontSet</Function> converter to create a font set in the
current locale.
<Function>XmFontListEntryLoad</Function> creates a font list entry that contains the
font or font set derived from the converter.
For more information about <Function>XtCvtStringToFontStruct</Function> and
<Function>XtCvtStringToFontSet</Function>, see <Emphasis>X Toolkit Intrinsics&mdash;C Language
Interface.</Emphasis>
</Para>
<Para><!-- Delete the following #ifdef'ed paragraph when the AES is unlocked.--><!-- Keep the #ifdef 1 paragraph at the bottom of the page.--></Para>
<VariableList>
<VarListEntry>
<Term><Symbol Role="Variable">display</Symbol></Term>
<ListItem>
<Para>Specifies the display where the font list will be used.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Symbol Role="Variable">font_name</Symbol></Term>
<ListItem>
<Para>Specifies an X Logical Font Description (XLFD) string,
which is interpreted either as a font name or as a base font name
list.
A base font name list is a comma-separated and NULL-terminated string.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Symbol Role="Variable">type</Symbol></Term>
<ListItem>
<Para>Specifies whether the <Symbol Role="Variable">font_name</Symbol> argument refers to a font name or
to a base font name list.
Valid values are <SystemItem Class="Constant">XmFONT_IS_FONT</SystemItem> and <SystemItem Class="Constant">XmFONT_IS_FONTSET</SystemItem>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term><Emphasis>tag</Emphasis></Term>
<ListItem>
<Para>Specifies the tag of the font list entry to be created.
The tag may be specified as <SystemItem Class="Resource">XmFONTLIST_DEFAULT_TAG</SystemItem>,
which is used to identify the default font list
element in a font list when specified as part of a resource.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</RefSect1>
<RefSect1>
<Title>RETURN</Title>
<Para>If the specified font is not found, or if the specified font
set cannot be created, then either an implementation-defined font will
be opened or a font set will be created, and a warning messge will be
generated. If no suitable font can be found or a font set cannot be created,
then another message will be generated and the function will return
NULL; otherwise the function returns a font list entry.
If the function returns a font list entry, the function allocates space
to hold the font list entry. The application is responsible for managing
the allocated space. The application can recover the allocated space by
calling <Function>XmFontListEntryFree</Function>.
</Para>
</RefSect1>
<RefSect1>
<Title>RELATED</Title>
<Para>&cdeman.XmFontList;,
&cdeman.XmFontListAppendEntry;,
&cdeman.XmFontListEntryCreate;,
&cdeman.XmFontListEntryFree;,
&cdeman.XmFontListEntryGetFont;,
&cdeman.XmFontListEntryGetTag;, and
&cdeman.XmFontListRemoveEntry;.
</Para>
</RefSect1>
</RefEntry>
<!--fickle 1.09 7/2/95-->
