CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-tns-core-modules

NativeScript Core Modules compatibility package for building native iOS and Android apps using JavaScript and CSS

Pending
Overview
Eval results
Files

platform-utils.mddocs/

Platform Utilities

Device information, platform detection, and native utility functions for iOS and Android integration. The platform utilities provide essential information about the runtime environment and cross-platform helper functions.

Capabilities

Platform Detection

Functions for detecting the current mobile platform and runtime environment.

/**
 * Platform detection functions
 */
function isAndroid(): boolean;
function isIOS(): boolean;

/**
 * Platform constants
 */
namespace platformModule {
  const platformNames: {
    android: "Android";
    ios: "iOS";
  };
}

Usage Examples:

import { isAndroid, isIOS } from "tns-core-modules";

// Platform-specific logic
if (isAndroid()) {
  console.log("Running on Android");
  // Android-specific code
} else if (isIOS()) {
  console.log("Running on iOS");
  // iOS-specific code
}

// Platform-specific styling or behavior
function getPlatformSpecificConfig() {
  return {
    statusBarStyle: isIOS() ? "light" : "dark",
    navigationStyle: isAndroid() ? "material" : "cupertino",
    hapticFeedback: isIOS()
  };
}

Device Information

Comprehensive device information including hardware specs, OS version, and device capabilities.

/**
 * Device information interface
 */
interface Device {
  // Hardware information
  readonly model: string;
  readonly deviceType: "Phone" | "Tablet" | "Unknown";
  readonly manufacturer: string;
  readonly uuid: string;
  
  // Operating system
  readonly os: string;        // "Android" or "iOS"
  readonly osVersion: string; // e.g., "14.5" or "11.0"
  readonly sdkVersion: string;
  
  // Localization
  readonly language: string;  // e.g., "en"
  readonly region: string;    // e.g., "US"
  
  // Capabilities
  readonly isTablet: boolean;
  readonly isEmulator: boolean;
}

/**
 * Device information access
 */
const device: Device;

Device Information Examples:

import { device } from "tns-core-modules";

// Log device information
console.log("Device Model:", device.model);
console.log("OS Version:", device.osVersion);
console.log("Language:", device.language);
console.log("Region:", device.region);
console.log("Is Tablet:", device.isTablet);
console.log("Is Emulator:", device.isEmulator);

// Device-specific logic
function configureAppForDevice() {
  const config = {
    // Adjust UI for tablet vs phone
    useTabletLayout: device.isTablet,
    
    // Enable debug features in emulator
    debugMode: device.isEmulator,
    
    // Localization
    defaultLanguage: device.language,
    defaultRegion: device.region,
    
    // Performance optimizations
    enableAnimations: !device.isEmulator,
    cacheSize: device.isTablet ? "large" : "medium"
  };
  
  return config;
}

// OS version checking
function checkOSCompatibility() {
  const osVersion = parseFloat(device.osVersion);
  
  if (device.os === "iOS") {
    if (osVersion < 12.0) {
      console.warn("iOS version too old, some features may not work");
    }
  } else if (device.os === "Android") {
    if (osVersion < 6.0) {
      console.warn("Android version too old, some features may not work");
    }
  }
}

Screen Information

Screen metrics and display information for responsive design and layout calculations.

/**
 * Screen metrics interface
 */
interface ScreenMetrics {
  readonly widthPixels: number;
  readonly heightPixels: number;
  readonly widthDIPs: number;
  readonly heightDIPs: number;
  readonly scale: number;
}

/**
 * Screen information interface
 */
interface Screen {
  readonly mainScreen: ScreenMetrics;
  readonly widthDIPs: number;
  readonly heightDIPs: number;
  readonly scale: number;
}

/**
 * Screen information access
 */
const screen: Screen;

Screen Information Examples:

import { screen } from "tns-core-modules";

// Get screen dimensions
console.log("Screen Width (DIPs):", screen.widthDIPs);
console.log("Screen Height (DIPs):", screen.heightDIPs);
console.log("Screen Scale:", screen.scale);

// Calculate pixel dimensions
const widthPixels = screen.widthDIPs * screen.scale;
const heightPixels = screen.heightDIPs * screen.scale;

console.log(`Physical resolution: ${widthPixels}x${heightPixels}`);

// Responsive design helper
function getScreenCategory(): "small" | "medium" | "large" | "xlarge" {
  const width = screen.widthDIPs;
  
  if (width < 360) return "small";
  if (width < 480) return "medium";
  if (width < 720) return "large";
  return "xlarge";
}

// Layout calculations
function calculateOptimalImageSize() {
  const screenWidth = screen.widthDIPs;
  const margin = 20;
  const columns = screenWidth > 480 ? 2 : 1;
  
  const imageWidth = (screenWidth - (margin * (columns + 1))) / columns;
  
  return {
    width: imageWidth,
    height: imageWidth * 0.75, // 4:3 aspect ratio
    columns: columns
  };
}

Utility Functions

Cross-platform utility functions for common mobile development tasks.

/**
 * Utility functions namespace
 */
namespace Utils {
  // Threading
  function executeOnMainThread(func: () => void): void;
  function mainThreadify<T extends Function>(func: T): T;
  function isMainThread(): boolean;
  function dispatchToMainThread(func: () => void): void;
  
  // Memory management
  function GC(): void;
  function releaseNativeObject(object: any): void;
  
  // URI and path utilities
  function isFontIconURI(uri: string): boolean;
  function isDataURI(uri: string): boolean;
  function isFileOrResourcePath(path: string): boolean;
  
  // System integration
  function openFile(filePath: string): boolean;
  function openUrl(url: string): boolean;
  function isRealDevice(): boolean;
  
  // Module utilities
  function getModuleName(path: string): string;
  
  // Layout utilities
  const layout: LayoutUtils;
  
  // Platform-specific utilities
  const android: AndroidUtils;
  const ios: IOSUtils;
}

Utility Functions Examples:

import { Utils } from "tns-core-modules";

// Thread management
function updateUIFromBackground(data: any) {
  // Ensure UI updates happen on main thread
  Utils.executeOnMainThread(() => {
    // Update UI elements
    console.log("Updating UI with data:", data);
  });
}

// Create main-thread wrapper function
const mainThreadCallback = Utils.mainThreadify((result: string) => {
  console.log("Result:", result);
});

// Check current thread
if (!Utils.isMainThread()) {
  console.log("Running on background thread");
}

// Memory management
function cleanupResources() {
  // Force garbage collection
  Utils.GC();
  
  // Release native objects
  Utils.releaseNativeObject(someNativeObject);
}

// System integration
function handleFileOpen(filePath: string) {
  const success = Utils.openFile(filePath);
  if (!success) {
    console.log("Failed to open file with system app");
  }
}

function handleUrlOpen(url: string) {
  const success = Utils.openUrl(url);
  if (!success) {
    console.log("Failed to open URL in browser");
  }
}

// URI validation
function validateImageSource(source: string): boolean {
  return Utils.isDataURI(source) || 
         Utils.isFileOrResourcePath(source) || 
         source.startsWith("http");
}

// Development helpers
function setupDevelopmentFeatures() {
  if (!Utils.isRealDevice()) {
    console.log("Running in emulator - enabling debug features");
    // Enable debugging features for emulator
  }
}

Layout Utilities

Utilities for layout calculations and responsive design.

/**
 * Layout utilities interface
 */
interface LayoutUtils {
  // Measurement conversion
  toDevicePixels(value: number): number;
  toDeviceIndependentPixels(value: number): number;
  
  // Layout measurement
  measureWidth(view: any): number;
  measureHeight(view: any): number;
  
  // Responsive helpers
  getDisplayMetrics(): {
    widthPixels: number;
    heightPixels: number;
    density: number;
    densityDpi: number;
  };
}

Platform-Specific Utilities

Platform-specific utility functions for Android and iOS integration.

/**
 * Android-specific utilities
 */
interface AndroidUtils {
  // Context access
  getApplicationContext(): any;
  getCurrentActivity(): any;
  
  // System services
  getSystemService(name: string): any;
  
  // Intent helpers
  createIntent(action: string): any;
  startActivity(intent: any): void;
  
  // Permissions
  requestPermissions(permissions: string[]): Promise<boolean>;
  hasPermission(permission: string): boolean;
}

/**
 * iOS-specific utilities
 */
interface IOSUtils {
  // View controller access
  getRootViewController(): any;
  getCurrentViewController(): any;
  
  // System integration
  openSettings(): void;
  canOpenUrl(url: string): boolean;
  
  // Notifications
  registerForPushNotifications(): void;
}

Platform-Specific Examples:

import { Utils, isAndroid, isIOS } from "tns-core-modules";

// Android-specific functionality
if (isAndroid()) {
  const context = Utils.android.getApplicationContext();
  const activity = Utils.android.getCurrentActivity();
  
  // Request camera permission
  Utils.android.requestPermissions(["android.permission.CAMERA"])
    .then(granted => {
      if (granted) {
        console.log("Camera permission granted");
      }
    });
  
  // Check if permission is already granted
  const hasCamera = Utils.android.hasPermission("android.permission.CAMERA");
}

// iOS-specific functionality
if (isIOS()) {
  const rootVC = Utils.ios.getRootViewController();
  
  // Check if can open settings
  if (Utils.ios.canOpenUrl("app-settings:")) {
    Utils.ios.openSettings();
  }
  
  // Register for push notifications
  Utils.ios.registerForPushNotifications();
}

// Cross-platform utility class
class PlatformHelper {
  static getDeviceInfo() {
    return {
      platform: isAndroid() ? "Android" : "iOS",
      isRealDevice: Utils.isRealDevice(),
      screenScale: screen.scale,
      screenSize: {
        width: screen.widthDIPs,
        height: screen.heightDIPs
      }
    };
  }
  
  static async requestCameraPermission(): Promise<boolean> {
    if (isAndroid()) {
      return Utils.android.requestPermissions(["android.permission.CAMERA"]);
    } else if (isIOS()) {
      // iOS handles camera permission automatically when accessing camera
      return Promise.resolve(true);
    }
    return Promise.resolve(false);
  }
  
  static openAppSettings(): void {
    if (isAndroid()) {
      const intent = Utils.android.createIntent("android.settings.APPLICATION_DETAILS_SETTINGS");
      Utils.android.startActivity(intent);
    } else if (isIOS()) {
      Utils.ios.openSettings();
    }
  }
}

Install with Tessl CLI

npx tessl i tessl/npm-tns-core-modules

docs

application.md

data-binding.md

file-system.md

http-client.md

image-handling.md

index.md

platform-utils.md

ui-components.md

tile.json