dominic/Tactility
1
0
Fork 0
mirror of https://github.com/ByteWelder/Tactility.git synced 2026-10-17 02:45:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

Comments updated

Browse Source
This commit is contained in:
Ken Van Hoeylandt 2026-09-04 08:51:43 +02:00
parent 3f11b76aae
commit d42c68ce3a
3 changed files with 25 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Modules/app-module/include/app/event.h
View File

@ -24,8 +24,8 @@ struct AppResultEventData {
uint32_t launch_id;
/** The child app instance's own AppMainFn/AppLoaderApi::run() return value. By convention:
* 0 = Ok, 1 = Cancelled, 2 = Error. Apps that need to hand back more than this (e.g. picked
* text, a path) expose their own "get last result" getter instead - see e.g.
* tt::app::inputdialog::getLastText(). */
* text, a path) write it to their own stdout instead, for the caller to read via an
* AppStream bound to it. See e.g. tt::app::inputdialog::start(). */
int32_t result;
};

21
Modules/app-module/include/app/execute.h
View File

@ -17,11 +17,9 @@ extern "C" {
/**
* Starts an app directly from @a location, without it having to be pre-registered via
* app_manager_add() first. Independent of the id-based app_start*() family
* (app/manager.h): performs no checks of its own beyond what AppLoaderApi::load() itself
* rejects. Not manifest lookup, and not whether @a location should be allowed to run (see
* app_is_executable() below): callers that need a check must run it themselves before calling
* this.
* app_manager_add() first.
* Performs no checks of its own beyond what AppLoaderApi::load() itself rejects.
* @warning It's advised to validate @a location with app_is_executable() first
* @param[in] stack stack allocation config for the app's task; all-zero uses the scheduler's
* default depth/capability, same as an AppManifest that leaves AppManifest::stack zeroed
* @retval ERROR_NOT_FOUND no AppLoaderApi is registered for @a location.type
@ -36,9 +34,8 @@ error_t app_execute(
);
/**
* Same as app_execute(), but as a modal child of @a parent_instance_id - see
* app_start_for_result()'s own doc for the result-delivery contract. Still no manifest
* and no check of its own beyond what AppLoaderApi::load() itself rejects.
* Same as app_execute(), but as a modal child of @a parent_instance_id.
* See app_start_for_result()'s own doc for the result-delivery contract.
* @retval ERROR_NOT_FOUND no AppLoaderApi is registered for @a location.type
* @retval ERROR_NONE on success
*/
@ -53,7 +50,7 @@ error_t app_execute_for_result(
/**
* Same as app_execute(), but installs @a bindings into the new instance's fd table before its
* task begins executing - see app_start_with_streams()'s own doc for stream ownership.
* task begins executing. See app_start_with_streams()'s own doc for stream ownership.
* @param[in] bindings see app_start_with_streams()
* @retval ERROR_NOT_FOUND no AppLoaderApi is registered for @a location.type
* @retval ERROR_OUT_OF_RANGE a binding's producer_fd is out of range
@ -90,9 +87,9 @@ error_t app_execute_for_result_with_streams(
);
/**
* Reports whether @a location is runnable on this target - the extension and header a loader
* requires (e.g. an ELF's class/data/type/machine), not whether it lives anywhere in particular:
* any executable app is runnable from any path. Cheap enough to call while listing a directory.
* Reports whether @a location is runnable on this target: the extension and header a loader
* requires (e.g. an ELF's class/data/type/machine), not whether it lives anywhere in particular.
* Any executable app is runnable from any path. Cheap enough to call while listing a directory.
* @return false if @a location can't be run, or if no AppLoaderApi is registered for its type
*/
bool app_is_executable(struct AppLocation location);

32
Modules/app-module/include/app/start.h
View File

@ -4,7 +4,7 @@
#include <app/manager.h>
/**
* This file contains functions to start and run apps that were registerd to the app manager.
* This file contains functions to start and run apps that were registered to the app manager.
* It differs from execute.h which runs executables from a specific path.
*/
@ -13,29 +13,27 @@ extern "C" {
#endif
/**
* Same as app_start(), but also passes @a argc/@a argv to the new instance's own main
* function (see app/loader.h's AppMainFn) - modelled on a C program's main(argc, argv). For
* regular (non-modal) navigations that need to pass data to the target app (e.g. "show details
* for this app id") without expecting a result back.
* Starts @a id, a manifest already registered via app_manager_add(), passing @a argc/@a argv to
* the new instance's own main function (see app/loader.h's AppMainFn), modelled on a C program's
* main(argc, argv). For regular (non-modal) navigations that need to pass data to the target app
* (e.g. "show details for this app id") without expecting a result back.
* @param[in] argv @a argc strings; app-module makes its own deep copy before returning, so
* @a argv and the strings it points to may be freed/go out of scope immediately after this call
* returns (e.g. safe to pass a stack-local array of a caller's own std::string::c_str()s).
* @retval ERROR_NOT_FOUND no manifest with this id is registered, or no AppLoaderApi is registered
* @retval ERROR_NONE on success
*/
error_t app_start(const char* id, int argc, const char* const argv[], AppInstanceId* out_app_instance_id);
/**
* Starts @a id as a modal child of @a parent_instance_id, for the purpose of receiving a
* result. The parent keeps running (window_manager's own multi-window stack handles burying its
* window while the child is shown).
* Starts @a id as a child of @a parent_instance_id, for the purpose of receiving a result.
*
* When the child's task exits, an APP_EVENT_RESULT is delivered to @a parent_instance_id -
* result is whatever the child's AppMainFn/AppLoaderApi::run() returned - unless
* When the child's task exits, an APP_EVENT_RESULT is delivered to @a parent_instance_id.
* The result is whatever the child's AppMainFn/AppLoaderApi::run() returned, unless
* @a parent_instance_id is 0, in which case no result is delivered (fire-and-forget, for
* callers with no app_instance_id of their own). The parent is then responsible for calling
* app_manager_stop() on the child's instance id to fully reap it. Children that need to hand
* back more than an int32_t (e.g. picked text, a path) expose their own "get last result"
* getter for the parent to call after receiving the event - see e.g.
* tt::app::inputdialog::getLastText().
* app_manager_stop() on the child's instance id to fully reap it.
*
* @param[in] argv @a argc strings; app-module makes its own deep copy before returning (same as
* app_start()), so @a argv and the strings it points to may be
* freed/go out of scope immediately after this call returns.
@ -62,10 +60,8 @@ error_t app_start_with_streams(const char* id, const struct AppStreamBinding* bi
* Combines app_start_for_result() and app_start_with_streams(): starts @a id as
* a modal child of @a parent_instance_id (see app_start_for_result()'s own doc for the
* result-delivery contract) with @a bindings installed into its fd table before its task begins
* executing (see app_start_with_streams()'s own doc for stream ownership). For a child
* that needs to hand back more than an int32_t (e.g. a path) via its own stdout instead of the
* "get last result" getter pattern (see app_start_for_result()) - see e.g.
* tt::app::fileselection::startForExistingFile().
* executing (see app_start_with_streams()'s own doc for stream ownership).
* For a child that needs to hand back more than an int32_t (e.g. a path) via its own stdout.
* @param[in] argv see app_start_for_result().
* @param[in] bindings see app_start_with_streams().
* @retval ERROR_NOT_FOUND no manifest with this id is registered, or no AppLoaderApi is registered