12. Applets

This chapter describes the libraries that are required in order to use the applets provided by the 3DS system.

The library provided by each applet can be used to start the applet from an application and use its features. The system generally allocates the memory required to start applets, but some applets require that the application pass the working memory. In addition, the application effectively stops while applets are running because they use the same CPU as the application after the operations of the called thread are stopped.

 

12.1. Library Applets

Features often used by applications are provided with 3DS as the following library applets.

  • Software Keyboard Applet
  • Photo Selection Applet
  • Mii Selection Applet
  • Sound Selection Applet
  • Error/EULA Applet
  • Circle Pad Pro Calibration Applet
  • EC Applet

 

Note:

The Mii Selection applet is provided in the CTR Face Library package.

 

 

12.1.1. Information Common to All Library Applets

The processing required to start and return from a library applet is basically the same as that used to start and return from the HOME Menu. Likewise, while a library applet is executing there are similar restrictions on using devices such as getting key input and rendering, and only the thread that called the library applet will stop it. Therefore, try not to execute unnecessary threads while library applets are executing. When creating threads that will continue to operate even while a library applet is running, note that the library applet creates threads with the priority settings shown in the following table. Set your thread priority so that it does not affect these thread processes.

Table 12-1. Priorities of Threads Created by Library Applets

Library Applet

Priority

Comments

(Common to all)

15

Used for notifications such as sleep notifications.

Software Keyboard Applet

17 to 20

 

Photo Selection Applet

16, 18, 20, 21, 25

 

Mii Selection Applet

17

 

Sound Selection Applet

16, 18

 

Error/EULA Applet

17, 20

 

Circle Pad Pro Calibration Applet

17 to 19

 

EC Applet

17, 22

Used for communication and related functions.

The application must support close processing when nn::applet::IsExpectedToCloseApplication returns true after control returns to the application in the same way as it returns to the application when nn::applet::WaitForStarting returns true while calling the function after the HOME Menu starts. However, when the POWER Button is pressed while the library applet is being displayed, the application transitions to a state where it has no rendering rights and at the same time where nn::applet::IsExpectedToProcessPowerButton returns true. If the application responds to the close request in this case, the screen refresh will halt during close processing. Please handle the POWER Button first in your implementation.

12.1.1.1. Recovering From Library Applets

When the HOME Button, the POWER Button, or the software reset button combination (L + R + START) is pressed while a library applet is starting, the application immediately recovers and the following behavior results.

Table 12-2. Behavior When Recovering From Library Applets

Button

Behavior

HOME Button

Returns a value as the return code indicating that the HOME Button was pressed. After recovery, nn::applet::IsExpectedToProcessHomeButton returns true.

POWER Button

Returns a value as the return code indicating that the POWER Button was pressed. After recovery, the nn::applet::IsExpectedToProcessPowerButton function returns true.

Software Reset

Returns a value as the return code indicating that there was a software reset.

12.1.1.2. Preloading

Library applets that support preloading can perform processes such as loading in advance. As a result, you can shorten the time that the screen freezes between the function call that starts the library applet and its display on the screen.

The names of the functions for preloading differ for each library applet, but basically they follow the same standards. Functions that begin the preloading process start with Preload. Functions that wait for preloading to complete start with WaitForPreload. And functions that cancel the preloading process start with CancelPreload.

When starting a preloaded library applet, you must wait for preloading to complete before starting. Note also that if you call a function that waits for completing without having first called a function that begins preloading, control never returns. However, this caution applies when both function calls take place on one thread. If the waiting-for-completion thread is different from the thread that begins preloading, control returns even if the order of the calls is reversed. Displaying the HOME Menu using nn::applet::ProcessHomeButton cancels preloading. If you navigate to the HOME Menu between calls to Preload and WaitForPreload, control does not return from WaitForPreload.

You cannot preload multiple library applets at the same time. To start a library applet other than one you have preloaded, you must first cancel the preload. Otherwise, after a library applet is started the preload is released, so there is no need to cancel the preload after recovery from a library applet.

12.1.2. Software Keyboard Applet

This library applet is called when an application requires text input from the user, such as for a user name or password. It displays a software keyboard in the lower screen and provides functionality for things such as entering passwords, restricting the number of characters input and which characters can be input, and the ability to filter prohibited words. The upper screen can either be made to darken or to continue displaying the application screen displayed when the software keyboard was started.

The nn/swkbd.h header file must be included and the libnn_swkbd library file must be added in order to use this library applet.

Parameters passed when starting the library applet are defined by the nn::swkbd::Parameter data structure. Detailed operational settings are made with the config (nn::swkbd::Config) member of parameters. However, initialization is required before configuration.

Code 12-1. Initializing Software Keyboard Operational Settings
void nn::swkbd::InitializeConfig(nn::swkbd::Config* pConfig); 

The Config structure passed in pConfig is initialized to the default settings. For operational settings that can be made in members of the Config structure, see the Applet Specifications.

The application must allocate work memory for this library applet. The size of the work memory required differs depending on the operational settings and can be obtained using the nn::swkbd::GetSharedMemorySize function.

Code 12-2. Getting the Work Memory Size for the Software Keyboard
s32 nn::swkbd::GetSharedMemorySize(
                const nn::swkbd::Config* pConfig,
                const void* pInitialStatusData = DELETEME,
                const void* pInitialLearningData = DELETEME); 

Pass a pointer to the Config structure used to make operational settings in pConfig.

If the operational settings of the software keyboard being used the last time it was run have been saved, you can restore that previous state by passing the start address for that data in pInitialStatusData. If this data does not need to be restored or it was not saved, specify NULL.

If training data for predictive text input has been saved with the operational settings of the software keyboard that were used the last time it was run, the training state last in effect can be restored by passing the start address for that data in pInitialLearningData. If this data does not need to be restored or it was not saved, specify NULL.

The start address of work memory must be allocated with 4096-byte alignment and its size must be a multiple of 4096 bytes. Furthermore, memory allocated from device memory must not be specified for the work memory.

After parameters have been set and work memory allocated, you can start the software keyboard using the nn::swkbd::StartKeyboardApplet function.

Code 12-3. Starting the Software Keyboard Applet
bool nn::swkbd::StartKeyboardApplet(
                nn::applet::AppletWakeupState* pWakeupState,
                nn::swkbd::Parameter* pParameter,
                void* pSharedMemoryAddr,
                size_t sharedMemorySize,
                const wchar_t* pInitialInputText = DELETEME,
                const nn::swkbd::UserWord* pUserWordArray = DELETEME,
                const void* pInitialStatusData = DELETEME,
                const void* pInitialLearningData = DELETEME
                nn::applet::AppTextCheckCallback callback = DELETEME); 

In pParameter, specify a pointer to the Parameter structure, which has the Config structure used to configure operational settings as one of its members. Information such as the input text string is stored in the structure specified by this argument.

Specify the start address and size of work memory in pSharedMemoryAddr and PSharedMemorySize.

If a UTF-16LE text string that is not NULL is passed in pInitialInputText, the software keyboard is run with the specified text string set in the input field.

In pUserWordArray, specify an array of words to register in the user dictionary.

Specify the same value obtained for the work memory size in pInitialStatusData and pInitialLearningData.

In callback, specify the callback function to use when the application is checking an input string. When the application does not perform a check due to its operation settings, this argument is ignored.

Startup fails if the return value of this function is false. Startup succeeds if the return value is true.

The software keyboard thread operates at a priority between 17 and 20. So even while the software keyboard is running, attention must be paid to the priority settings of threads that continue to operate.

12.1.3. Photo Selection Applet

This library applet is used to select the data for one photo from among those registered in the Nintendo 3DS camera album for use by the application. You can specify extraction conditions such as the capture time and type when starting the applet. You can also filter the data to be listed. Note that the applet can only select photos that are saved on an SD card.

To use this library applet, you must include the nn/phtsel.h header file and add the libnn_phtsel library file.

Parameters to be passed when this library applet is started are defined in the nn::phtsel::Parameter structure. Basic operational settings are made in the m_config member (nn::phtsel::Config structure). Detailed settings such as extraction conditions are made in the m_input member (nn::phtsel::PhtselInput structure). The execution result is stored in the m_output member (nn::phtself::PhtselOutput structure). For the available settings and other information, see the sample demo.

The application must allocate work memory when the applet background displays images captured by the application. The size required by work memory can be obtained using the nn::phtsel::GetWorkBufferSize function.

Code 12-4. Getting the Work Memory Size for Photo Selections
size_t nn::phtsel::GetWorkBufferSize(); 

The start address of work memory must be allocated with 4096-byte alignment and its size must be a multiple of 4096 bytes. Furthermore, memory allocated from device memory must not be specified for the work memory.

After the parameters have been set and the work memory allocated, you can start the photo selection library applet using the nn::phtsel::StartPhtsel function. Call the nn::phtsel::StartPhtselNoCapture function if the applet background does not display images captured by the application.

Code 12-5. Starting the Photo Selection Library Applet
nn::applet::AppletWakeupState nn::phtsel::StartPhtsel(
                nn::phtsel::Parameter* pParameter, void* pWorkBuffer);
nn::applet::AppletWakeupState nn::phtsel::StartPhtselNoCapture(
                nn::phtsel::Parameter* pParameter); 

In pParameter, specify the pointer to the Parameter structure for which settings were performed. Specify the start address of work memory in pWorkBuffer.

Execution results are stored in the m_output member of pParameter upon return to the application.

12.1.4. Mii Selection Applet

This library applet is called when using Mii characters in an application to select from among registered Mii characters. You can select only one registered Mii or one guest Mii (six are available by default). You can also select whether to display a list of guest Mii characters and whether to display the operating screen in the upper or lower screen.

Note:

To use the Mii Selection applet from inside your application, you must use the CTR Face Library (middleware).

For instructions on using this library, see the CTR Face Library documentation.

12.1.5. Sound Selection Applet

This library applet is called when selecting sound data recorded using Nintendo 3DS Sound for a sound to be used, such as an application sound effect. Only one instance of sound data can be selected. This applet cannot be used to record sounds, sort data, delete data, or otherwise manipulate data. Note that the applet can only select sound data that is saved on an SD card.

To use this library applet, you must include the header file (nn/voicesel.h) and add the library file (libnn_voicesel).

The nn::voicesel::Parameter structure defines the parameters to pass into the library applet when starting it. Use the parameter's config member (nn::voicesel::Config structure) to configure basic operations, and the input member (nn::voicesel::Input structure) to configure advanced features, such as extraction conditions. The results are stored in the output member (nn::voicesel::Output structure). For the available settings and other information, see the sample demo.

After you are finished configuring the parameters, you can start the sound selection library applet by calling nn::voicesel::StartVoiceSel.

Code 12-6. Starting the Sound Selection Applet
nn::applet::AppletWakeupState nn::voicesel::StartVoiceSel(
                nn::voicesel::Parameter* pParameter); 

In pParameter, specify the pointer to the Parameter structure for which settings were performed.

When control returns to the application, pParameter 's output member will store the results of execution.

12.1.6. Error/EULA Applet

When using wireless-based communication features such as StreetPass, you must check the EULA (the licensing agreement related to Nintendo 3DS network services) and gain the consent of the user. If an application that uses these communication features has not confirmed that the user has agreed to the latest EULA and gained the user’s consent, you can use this library applet to display the EULA and get consent. Acceptance of the EULA is required to use communication features, but applications are not required to display the EULA. If the application does not display the EULA, display an error at the time of communication and guide the user to System Settings.

Not only does this library applet display the EULA, it can also display error messages. As long as infrastructure communication-related libraries (such as AC and FRIENDS) are being used, the correct corresponding error message is displayed when an error code is passed to the applet. You can also display proprietary error messages from the application.

To use this library applet, you must include the nn/erreula.h header file and add the libnn_erreula library file.

Parameters to be passed when this library applet is started are defined in the nn::erreula::Parameter structure. Error codes, error messages, and operational settings are made in the config member (nn::erreula::Config structure). Be sure to configure the setting after initializing with the nn::erreula::InitializeConfig function. For more information about parameter settings, refer to the Applet Specifications and sample demos.

After you set the parameters and allocate the work memory, you can start the Error/EULA applet using the nn::erreula::StartErrEulaApplet function.

Code 12-7. Starting the Error/EULA Applet
void nn::erreula::StartErrEulaApplet(
                nn::applet::AppletWakeupState* pWakeupState,
                nn::erreula::Parameter* pParameter); 

In pParameter, specify the pointer to the Parameter structure for which settings were performed.

If the EULA display is made by the setting, the agreement sequence of the Network Services Agreement is displayed and the result of agreement or disagreement to the Network Services Agreement is returned to the application.

All of the infrastructure communication features associated with the application, as well as StreetPass communication, will return the EULA disagreement error if the user does not agree to the Network Services Agreement in the version that the application requires. NEX login, registration of download tasks, creation of StreetPass box, etc., will all be subject to the agreement. The version of the Network Services Agreement that requires an agreement will automatically be embedded in ROM. Be sure to confirm whether the Network Services Agreement is required with the nn::cfg::IsAgreedEula function, and call back this applet if the agreement is not accepted. Only when the applet is called back in the state of not agreeing to the Network Services Agreement, will “EULA agreement” or “EULA disagreement” be returned correctly.

12.1.7. Circle Pad Pro Calibration Applet

This library applet is used for calibrating the feel of controls on the Right Circle Pad installed in the Circle Pad Pro. Applications supporting the Circle Pad Pro must provide a start scene for this applet so that users can calibrate the feel of controls on the Right Circle Pad.

Note:

The C Stick on SNAKE functions like the Right Circle Pad on a permanently connected Circle Pad Pro. If an application running on SNAKE calls the Circle Pad Pro Calibration Applet, a message describing how to calibrate the C Stick is displayed.

To use this library applet, you must include the header file (nn/extrapad.h) and add the library file (libnn_extrapad).

The parameter passed when the library applet is started is defined by the nn::extrapad::Parameter structure. Operating settings are performed in the config parameter member variables (nn::extrapad::Config structure). Always perform initialization with the nn::extrapad::InitializeConfig function before performing settings for whether to support the HOME Button and software reset.

When parameter setting procedures are complete, you can start the library applet with the nn::extrapad::StartExtraPadApplet function.

Code 12-8. Starting the Circle Pad Pro Calibration Applet
void nn::extrapad::StartExtraPadApplet(
                nn::applet::AppletWakeupState* pWakeupState,
                nn::extrapad::Parameter* pParameter); 

In pParameter, specify the pointer to the Parameter structure for which settings were performed.

12.1.8. EC Applet

The EC applet is a library applet for purchasing and managing add-on content and service items.

Note:

For more information about EC features, see the CTR-SDK API Reference.

12.2. System Applets

A system applet is generally an applet that is started from the HOME Menu, but libraries are provided to start and use the applets from an application. The processing required to start and return from a system applet from an application is basically the same as that used to start and return from the HOME Menu.

12.2.1. Internet Browser Applet

The WEBBRS library lets you start the built-in Internet browser by specifying a URL from an application. The startup method is similar to that of a library applet, but it differs in that closing the Internet browser that was started results in returning to the HOME Menu with the application suspended.

Warning:

Depending on which system updates have been applied, there may be systems that do not have the Internet browser installed. For this reason, it is necessary to check whether the Internet browser is installed on the system before starting it.

Note:

For more information about the WEBBRS library, see the CTR-SDK API Reference.

12.2.2. Miiverse Application and Post App

The OLV library enables the use of Miiverse features in an application. This makes it possible to start the Miiverse application or Post app and receive post data from within an application. These are referred to as "applications" but are actually included with the system applets.

Note:

For more information about the OLV library, see the CTR-SDK API Reference.

 

 

 

12.2.2.1. Starting an Application From the Miiverse Post Page

Applications can be started from a post in Miiverse.

The application must be configured as follows to enable this feature.

  • Specify EnableMiiverseJumpArgs:True in the BSF file.
  • Specify FLAG_APP_STARTABLE flag with the nn::olv::UploadPostDataByPostApp function when posting.

Operation in the Miiverse Application

When you view a post with the flag above set in the Miiverse application, a Launch button appears in the post. Any user who owns the application can use this button to start it. Users who do not own the application can view the post but cannot start the application.

Figure 12-1. Starting an Application From the Post Page

Miiverse Post App Miiverse Post Post App


CONFIDENTIAL