<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../../docs.xsl"?>

<docs type="symbol" project="SIEGE" version="0.8.2" rpath="../..">
	<file root="siege/core" name="window.DONE.h">
		<group key="Window" name="Window">
			<symbol id="17" kind="function" internal="false" cname="sgWindow*Title*">
				<index>
					<centry key="Window*Title*">sgWindow*Title*</centry>
					<entry key="WindowSetTitlef">sgWindowSetTitlef</entry>
					<entry key="WindowSetTitlefv">sgWindowSetTitlefv</entry>
					<entry key="WindowSetTitle">sgWindowSetTitle</entry>
					<entry key="WindowGetTitle">sgWindowGetTitle</entry>
				</index>
				<section name="Name">
					<names>
						<name>sgWindowSetTitlef</name>
						<name>sgWindowSetTitlefv</name>
						<name>sgWindowSetTitle</name>
						<descr>Set the window title</descr>
					</names>
					<names>
						<name>sgWindowGetTitle</name>
						<descr>Get the window title</descr>
					</names>
				</section>
				<section name="Synopsis">
					<code-block lang="C">void <ref local="true" path="." file="window.DONE" group="Window" name="sgWindow*Title*" id="17">sgWindowSetTitlef</ref>(const char* format, ...);
void <ref local="true" path="." file="window.DONE" group="Window" name="sgWindow*Title*" id="17">sgWindowSetTitlefv</ref>(const char* format, va_list args);
void <ref local="true" path="." file="window.DONE" group="Window" name="sgWindow*Title*" id="17">sgWindowSetTitle</ref>(const char* title);

char* <ref local="true" path="." file="window.DONE" group="Window" name="sgWindow*Title*" id="17">sgWindowGetTitle</ref>(void);</code-block>
				</section>
				<section name="Parameters">
					<params>
						<name>format</name>
						<descr>`printf`-like format string</descr>
					</params>
					<params>
						<name>...</name>
						<name>args</name>
						<descr>variadic arguments for the format</descr>
					</params>
					<params>
						<name>title</name>
						<descr>unformatted title to set</descr>
					</params>
				</section>
				<section name="Description">
					<p>
						The <ref local="true" path="." file="window.DONE" group="Window" name="sgWindow*Title*" id="17">sgWindowSetTitle</ref>* family of functions modify the window's displayed title, both in the window itself and (if applicable) in the taskbar.
					</p>
					<p>
						The string in the argument is copied internally, so once the title is set, it may freely be deallocated or modified.
					</p>
					<p>
						<ref local="true" path="." file="window.DONE" group="Window" name="sgWindow*Title*" id="17">sgWindowSetTitlef</ref>() and <ref local="true" path="." file="window.DONE" group="Window" name="sgWindow*Title*" id="17">sgWindowSetTitlefv</ref>() are similar to the basic <ref local="true" path="." file="window.DONE" group="Window" name="sgWindow*Title*" id="17">sgWindowSetTitle</ref>(), except that they take in a format string and variadic arguments. Their calls are roughly equivalent to:
					</p>
						<code-block lang="C">// `buf` is large enough
vsnprintf(buf, len, format, args); // for the `fv` variant
<ref local="true" path="." file="window.DONE" group="Window" name="sgWindow*Title*" id="17">sgWindowSetTitle</ref>(buf);</code-block>
				</section>
				<section name="Return Values">
					<p>
						<ref local="true" path="." file="window.DONE" group="Window" name="sgWindow*Title*" id="17">sgWindowGetTitle</ref>() returns the current window title; the returned string is non-const only for convenince reasons -- it should not be modified.
					</p>
					<p>
						If the title has not been set, it returns NULL.
					</p>
				</section>
				<section name="Examples">
					<code-block lang="C"><ref local="true" path="." file="window.DONE" group="Window" name="sgWindow*Title*" id="17">sgWindowSetTitlef</ref>("My Game - FPS: %.2f", fps);</code-block>
				</section>
				<section name="See Also">
					<sees>
						<see><ref local="false" path="." file="window.DONE" group="Window" name="sgWindowSetIcon" id="16">sgWindowSetIcon</ref></see>
					</sees>
				</section>
				<section name="TODO">
						<ul>
							<li>
								<p>
									(?) Return empty string for non-set title
								</p>
							</li>
						</ul>
				</section>
			</symbol>
		</group>
	</file>
</docs>
