1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xml:lang="en-US" lang="en-US" xmlns="http://www.w3.org/1999/xhtml">
3  <head>
4    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5    <meta http-equiv="Content-Style-Type" content="text/css" />
6    <link rel="stylesheet" href="../../../css/manpage.css" type="text/css" />
7<title>ProcessHomeButton</title>
8  </head>
9  <body>
10<h1><CODE><a href="../../../nn/Overview.html">nn</a>::<a href="../../../nn/applet/Overview.html">applet</a>::<a href="../../../nn/applet/CTR/Overview.html">CTR</a>::ProcessHomeButton</CODE> Function</h1>
11<h2>Syntax</h2>
12    <div class="section">
13      <pre class="definition">
14bool ProcessHomeButton(
15     void
16);
17</pre>
18    </div>
19<h2>Parameters</h2>
20    <div class="section">
21<p>None.</p>
22    </div>
23<h2>Return Values</h2>
24<div class="section">Returns a value indicating whether it is necessary to wait. </div>
25<h2>Description</h2>
26    <div class="section">
27<p>Processes transitions to the HOME Menu.</p><!-- write here --><P>
28This function is used to jump to the HOME Menu when this is required by the <a href="../../../nn/applet/CTR/IsExpectedToProcessHomeButton.html"><CODE>nn::applet::CTR::IsExpectedToProcessHomeButton</CODE></a> function.
29</P><P>
30The return value indicates whether it is necessary to wait with the <a href="../../../nn/applet/CTR/WaitForStarting.html"><CODE>nn::applet::CTR::WaitForStarting</CODE></a> function after this function is called. If this is <CODE>true</CODE>, call the function. If this is <CODE>false</CODE>, you do not need to call the function. (Of course, even if you call the function it will simply exit without waiting.)
31</P><P>
32To ensure mutual exclusion with Sleep Mode, you must call <CODE><a href="../../../nn/applet/CTR/DisableSleep.html">nn::applet::CTR::DisableSleep</a>(true)</CODE> before calling this function. You must call <CODE><a href="../../../nn/applet/CTR/EnableSleep.html">nn::applet::CTR::EnableSleep</a>(true)</CODE> after waiting and determining to finish waiting. (Note that the above constraint is specific to the current version and may change in the future.)
33</P><P>
34You must also initialize the graphics library using the <CODE>nngxInitialize</CODE> function before calling this function. Also, after the display buffer has been set and buffers have been swapped once, you must turn on the LCD screens.
35</P><P>
36If the LCD screens are not turned on, the upper and lower screens will remain black even if you return to the HOME Menu. (Background music and sound effects will play normally, and key input will be handled as usual.) Although this function can be called even if a display buffer has not been configured, the image shown when the LCDs are turned on may be undefined.
37</P><P>
38Example
39</P><PRE>
40   // HOME Button transition check
41   if ( applet::IsExpectedToProcessHomeButton() )
42   {
43       _save_my_data();
44       applet::DisableSleep(true);
45
46       // HOME Button transition process
47       <FONT color="red">applet::ProcessHomeButton();</FONT>
48
49       // Wait
50       applet::WaitForStarting();
51
52       if( applet::IsExpectedToCloseApplication() )
53       {
54             _close_application();
55       }
56
57       applet::EnableSleep(true);
58       _recover_my_data();
59   }
60</PRE><P>
61Before calling this function, be sure that rendering has finished by calling the <CODE>nngxWaitCmdlistDone</CODE> function. For frameworks where multiple command lists will be swapped and commands will be created in parallel with rendering, pay close attention to the timing of <a href="../../../nn_gx/nngxRunCmdlist.html"><CODE>nngxRunCmdlist</CODE></a> function calls.<br />The GPU may hang if rendering has not completed before this function is called.<BR>If rendering has not yet completed at the time that this function is called (while a command request is processing), execution halts on an assertion (only for the Development/Debug builds).<br />In addition, after returning from an applet such as the HOME Menu, be sure to reset all necessary registers because GPU register values will have been updated if the return value of <a href="../../../nn/applet/CTR/IsExpectedToCloseApplication.html"><CODE>nn::applet::CTR::IsExpectedToCloseApplication</CODE></a> is <CODE>false</CODE>.
62</P><PRE>
63   /* When using the GL library */
64   nngxUpdateState(NN_GX_STATE_ALL);
65
66   /* When using the GD library */
67   nn::gd::System::ForceDirty(nn::gd::MODULE_ALL);
68
69   /* When using the GR library */
70   // There is no API for returning settings because internal settings are not maintained.
71   // Create all necessary commands for the next rendering pass.
72
73   /* Others */
74   // Reset all necessary registers for the next rendering pass.
75</PRE><BR /><P>If <CODE>HomeButtonCallback</CODE> has been set by the <CODE><a href="../../../nn/applet/CTR/SetHomeButtonCallback.html">nn::applet::CTR::SetHomeButtonCallback</a></CODE> function, do not call this function until after the process has left the callback.  (If you call the function beforehand, the process might become deadlocked.)
76</P><P>
77Although old versions of the library had the <CODE>nn::applet::CTR::ProcessHomeButtonIfPrepared</CODE> function, it has the exact same behavior as this function. Use this function instead.
78</P><P>
79If any library applets have been preloaded, calling this function cancels those preloads when the transition occurs.
80</P><P>
81You need to pay attention to race conditions with this function when you preload library applets in another thread. For example, if the <a href="../../../nn/applet/CTR/IsExpectedToProcessHomeButton.html"><CODE>nn::applet::CTR::IsExpectedToProcessHomeButton</CODE></a> function detects the HOME Button and this function is later called in the same thread but library applets are preloaded in another, an assert statement will trigger a warning because of an inconsistency in internal states.
82</P></div>
83<h2>Revision History</h2>
84    <div class="section">
85      <dl class="history">
86        <dt>2012/02/07</dt>
87<dd>	        Noted that execution halts on an assertion if rendering has not yet completed at the time this function is called. <br />
88        </dd>
89        <dt>2012/01/16</dt>
90<dd>	        Added a specific example about limitations when calling this function (the need to wait for rendering to complete).<BR>
91        </dd>
92        <dt>2011/11/01</dt>
93<dd>Added precautions related to race conditions associated with preloading library applets.<br />
94        </dd>
95        <dt>2011/09/08</dt>
96<dd>Added information about rendering before and after calling this function.<BR>
97        </dd>
98        <dt>2011/08/01</dt>
99<dd>Added information about limitations related to display buffer swapping and the LCD screens when calling this function.<BR>
100        </dd>
101        <dt>2011/07/11</dt>
102<dd>Added the fact that preloading of library applets is canceled when this function is called.<BR>
103        </dd>
104        <dt>2011/03/30</dt>
105<dd>Added note about the need for the <CODE>nngxInitialize</CODE> function.
106        </dd>
107        <dt>2011/02/17</dt>
108<dd>Added a cautionary note about setting the callback.<br />
109        </dd>
110        <dt>2011/01/24</dt>
111<dd>Added mention of the <CODE>DisableSleep</CODE> and <CODE>EnableSleep</CODE> functions.<br />
112        </dd>
113        <dt>2010/12/10</dt>
114<dd>Added information about the removal of <CODE>ProcessHomeButtonIfPrepared</CODE>.
115        </dd>
116        <dt>2010/11/10</dt>
117<dd>Initial version.<br />
118        </dd>
119      </dl>
120    </div>
121  <hr><p>CONFIDENTIAL</p></body>
122</html>
123