cellphonepopup.h

/* ScummVM - Graphic Adventure Engine
 *
 * ScummVM is the legal property of its developers, whose names
 * are too numerous to list here. Please refer to the COPYRIGHT
 * file distributed with this source distribution.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.

 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.

 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 */

#ifndef NANCY_UI_TASKBAR_CELLPHONEPOPUP_H
#define NANCY_UI_TASKBAR_CELLPHONEPOPUP_H

#include "engines/nancy/commontypes.h"
#include "engines/nancy/enginedata.h"
#include "engines/nancy/renderobject.h"

namespace Nancy {

struct NancyInput;

namespace UI {

// Nancy 10+ cell phone popup, driven by the UICL chunk. Handles dialling and
// calls, the contacts directory, the online hub (e-mail / web search / browser,
// or the Nancy 13 camera), the help page, and the Nancy 13 photo camera.
class CellPhonePopup : public RenderObject {
public:
    CellPhonePopup();
    ~CellPhonePopup() override = default;

    void init() override;
    void registerGraphics() override;
    void updateGraphics() override;
    void handleInput(NancyInput &input);

    void open();
    void close();
    void toggle() { if (_isVisible) close(); else open(); }

    // True once a call has connected and the popup has scene-changed into the
    // conversation. The phone is just decoration then and the conversation
    // textbox is the active UI, so the cursor must not be confined to the phone.
    bool isInCall() const { return _screenState == kConnected; }

    // Swaps the welcome graphic for the No Signal / No Access / Old Email
    // Only labels and blocks outgoing calls.
    void setNoSignal(bool noSignal);

    // Swaps the battery sprite for the low/dead variant.
    void setBatteryLow(bool low);

    // Insert or replace a contact (matched by its 11-byte dial pattern).
    // Used by AR 130 to add/modify entries at runtime.
    void upsertContact(const UICL::Contact &c);

    // Append an entry to the email results list (mode 0) or the web
    // bookmarks list (mode 1). Driven by AR 131 (AddSearchLink) and the
    // UICL chunk's initial entries.
    void addSearchLink(int16 mode, const SearchLink &link);

    // Phone-call return scene. Set before jumping into a conversation scene
    // so AR 128 (CellPhonePopCellSceneFromStack) can return there without
    // trampling the global push slot used by closeups/inventory views.
    void setReturnScene(const SceneChangeDescription &scene);
    bool consumeReturnScene(SceneChangeDescription &out);

    // Start an incoming-call sequence: opens the popup, stores the
    // destination scene, and joins the kPlaceCall state chain so it
    // rings, picks up, shows the connecting sprite, and changeScenes
    // into `scene` (AR 128 returns via the setReturnScene slot).
    void startIncomingCall(const SceneChangeDescription &scene);

    // Called by AR 128 when a call's conversation ends. An incoming call takes
    // the phone down; a player-placed call leaves it open at the welcome screen
    // (matching the original CCellPhonePopCellSceneFromStack).
    void endCall();

private:
    enum ScreenState : int {
        kWelcome          = 0,
        kDialing          = 1,
        kPlaceCall        = 2,
        kWaitOutgoingRing = 3,
        kLookupContact    = 4,
        kWaitPickup       = 5,
        kConnected        = 6,
        kInvalidNumber    = 7,
        kWaitInvalid      = 8,
        kDirectory        = 9,
        kOnlineHub        = 10,  // Online heading + Email / Web sub-buttons
        kWebList          = 11,  // web search-results list (AR-131 mode 1)
        kEmailList        = 12,  // email message list (AR-131 mode 0)
        kContentView      = 13,  // full-text view of a single email / page

        // Nancy 13 camera feature (the web browser was removed; Menu offers
        // "view pictures" instead).
        kCamera           = 14,  // framing the live viewport before a snapshot
        kPictureView      = 15,  // reviewing a captured photo (Cam/Del/Send)
        kDeleteConfirm    = 16,  // "DELETE? YES OR NO" over a photo
        kMessageScreen    = 17   // a transient message tile (SENT / DELETED / FULL)
    };

    Common::Rect zoomedChromeSrc() const;
    void drawChrome();
    void drawScreenContent();
    void drawStatusIcons(bool includeSignal = true);
    void drawWebDirLabels();
    void drawDialLabel();
    // Blit one ribbon label sprite (Cam / Menu / Dir / Del / Send / Yes / No)
    // from the sprite atlas at its chunk dest.
    void drawRibbonLabel(const UICL::SrcDestRectPair &label);
    void drawRibbonLabelAt(const Common::Rect &src, const Common::Rect &dest);
    void drawTypeMessage();
    void drawConnectedLabel();
    void drawConnectingSprite();
    void drawDialedNumber();
    void drawHelpButton(uint state);
    void drawCloseButton(bool hovered);
    void drawStatusLabels();
    void drawDirectoryList();
    void drawDirectoryArrows();
    // Blit one scroll/paging arrow (idle, or its pressed sprite when hovered).
    void drawScrollArrow(const UICL::ThreeRectWidget &arrow, bool hovered);
    void drawWelcomeScreen();
    // Nancy 13: blit one UI_Cell_Xtra atlas tile into the LCD area (the plain
    // keyboard background or one of the message tiles). These are fixed atlas
    // positions the original bakes into a pre-rendered per-state LCD surface.
    void drawLcdTile(const Common::Rect &src);
    // Show a transient message tile (Picture Sent / Deleted / Camera Full),
    // dismissed by any click back to returnState.
    void showMessageScreen(const Common::Rect &tileSrc, ScreenState returnState);
    // Nancy 13: draw the current captured photo (scaled into the LCD) for the
    // "view pictures" screen, or the "no pictures" tile when there are none.
    void drawPictureView();
    // The captured pictures store, lazily created (Nancy 13 only). May be null.
    struct CellPhonePictureData *pictureData() const;
    // Nancy 13 camera: grab the given screen-space region of the live viewport
    // into a new persisted CapturedPicture and select it. Empty rect = the whole
    // viewport.
    void captureViewport(const Common::Rect &screenRegion = Common::Rect());

    // Nancy 13 camera framing: while kCamera is active the popup covers the
    // viewport and draws a movable rectangle marking the shot. Entering saves the
    // phone's rect and grows the draw surface; exiting restores it.
    void enterCameraFraming();
    void exitCameraFraming();
    void drawCameraFraming();
    // Screen-space rect of the framing box, centred on the mouse and clamped to
    // the viewport.
    // Each paging arrow is only drawn and live while its side has a photo.
    bool canPageToPreviousPicture() const;
    bool canPageToNextPicture() const;
    Common::Rect framingScreenRect() const;
    // Marks the shown snapshot sent and fires the flags of every subject in it
    // addressed to the contact on the given directory row.
    void sendCurrentPicture(uint listRow);
    // Blit a sub-button's idle sprite at its chunk dest (used for the visible
    // Back buttons: subButtons[0] on the help / directory / online screens,
    // subButtons[7] in the zoomed email / browser content view).
    void drawBackButton(uint subButtonIndex);
    // Blit an online-hub option button (mail / browser), using its highlighted
    // sprite when the cursor is over it.
    void drawHubButton(uint subButtonIndex);
    // Blit the lit key sprite of the currently held dial-pad slot over its
    // dest rect, so keypad keys visually depress while pressed.
    void drawPressedDialKey();

    // Generic list renderer used by web / email modes.
    void drawLinkList();
    // Blit a heading sprite (e.g. emailHeading) at its chunk dest. The
    // heading sits in the title-bar strip above the LCD content.
    void drawHeading(const UICL::SrcDestRectPair &heading);
    // Render the opened entry's body text in the LCD area, word-wrapped.
    void drawContentView();
    // Expensive: render the current content page's hypertext into the cache
    // surface (+ text height, image/link hotspots). Called by drawContentView
    // only when the page key changes.
    void renderContentPage(int surfaceWidth);
    // The LCD area the content view renders into: the small screen for the help
    // page, the taller zoomed-in one for browser / email articles.
    const Common::Rect &contentViewScreenRect() const;
    // Per-click scroll amount (pixels) for the article/help content view.
    uint contentScrollStep() const;
    // Enter the content view for a list entry whose AUTOTEXT key is `key`.
    void openContentView(const Common::String &key, const UICL::SrcDestRectPair &heading);
    // Web button: open the first url entry as the browser home page (page 0).
    void openBrowserHome();

    // Up/down scroll buttons differ by mode: subButtons[1]/[2] for the
    // directory's narrower list area, [5]/[6] for the taller search /
    // email / browser-content LCD area.
    const UICL::ThreeRectWidget &scrollUpButton() const;
    const UICL::ThreeRectWidget &scrollDownButton() const;

    // True when the current screen uses the zoomed-in (no-keypad)
    // chrome variant: search list, email list, and content view.
    bool isZoomedChromeState() const {
        return _screenState == kWebList ||
                _screenState == kEmailList ||
                _screenState == kContentView;
    }

    // The help "?" page reuses the content-view state, but unlike browser /
    // email articles the original renders it in the regular (keypad-visible)
    // chrome and the small LCD, not the zoomed full-screen variant.
    bool isHelpContentView() const {
        return _screenState == kContentView && _uiclData &&
                _contentHeading == &_uiclData->helpHeading;
    }

    // True for screens that hide the status icons and "?" button so the
    // top bar shows only the section heading and the up arrow.
    bool isSubScreenState() const {
        return _screenState == kDirectory ||
                _screenState == kOnlineHub ||
                isZoomedChromeState();
    }

    void resetDialPad();
    void enterScreenState(ScreenState newState);
    // With no signal the phone locks to "Old Email Only": on the welcome,
    // dialing and online-hub screens every keypad key is dead except Menu
    // (the Menu key), which still reaches the e-mail list. Digits, *, #, Talk, Dir
    // and the Help "?" go inert. The directory keeps its keys so the reachable
    // e-mail path still works.
    bool isDialKeyActive(uint slot) const;
    // True while a player-placed call is ringing / waiting for pickup, so the
    // connecting strip shows a Back button (subButtons[0]) that cancels it.
    // Incoming calls have no Back button.
    bool isCallBackButtonActive() const {
        return (_screenState == kPlaceCall || _screenState == kWaitOutgoingRing ||
                _screenState == kLookupContact || _screenState == kWaitPickup) &&
                !_hasPendingCallScene && _uiclData &&
                !_uiclData->subButtons[0].destRect.isEmpty();
    }
    // Cancel a ringing / waiting call and return to the welcome screen.
    void cancelCall();
    void appendDigit(byte slotIndex);
    // Play a dial-pad key's DTMF tone. The name is a raw sound filename, so it
    // is played through the phone's call-sound channel rather than the common
    // (boot-registered) sound table.
    void playDialPadSound(const Common::String &name);
    // Play a popup button's click sound (the close X), like the inventory
    // popup. Falls back to the shared button-click slot in the popup header.
    void playButtonClickSound(const UIButtonRecord &button);
    bool playSoundIfPresent(const Common::Path &soundName);
    bool callSoundIsStillPlaying() const;
    void triggerContactCallSceneChange(uint contactIndex);
    int findContactByDialBuffer() const;

    // LCD content bounds the directory list is laid out against.
    const Common::Rect &lcdListBounds() const;
    uint maxDirectoryRows() const;
    uint directoryRowAt(const Common::Point &chunkMouse) const;
    Common::Rect directoryRowRect(uint visibleIndex) const;
    // Row pitch and first-row Y (screen coords) from the layout data.
    int rowPitch() const;
    int rowTopScreen() const;
    bool isLinkListMode() const { return _screenState == kWebList || _screenState == kEmailList; }
    bool isOnlineMode() const { return _screenState == kOnlineHub || isLinkListMode(); }

    // Section headings live in the phone's title-bar strip above the LCD,
    // so they don't consume a list row. Kept as a hook in case a game
    // needs an in-LCD title row.
    uint listTitleRows() const { return 0; }

    // Whether the phone itself takes and shows pictures, i.e. whether the Menu
    // screen offers "View Pictures" and the top row carries the Cam label.
    bool hasCameraFeature() const;

    // Layout for the two clickable labels on the Online hub.
    Common::Rect hubEmailRect() const;
    Common::Rect hubWebRect() const;
    void startCallToContact(uint contactIndex);
    // Directory row -> raw contact index, or -1.
    int contactIndexForVisibleRow(uint visibleRow) const;
    uint visibleContactCount() const;
    // Entry count for whichever list the popup is currently showing.
    uint currentListEntryCount() const;
    // Absolute indices into the current list's backing array that pass
    // the active filter. Email applies the "Old Email Only" filter
    // (no-signal -> read messages only); web shows everything.
    Common::Array<uint> listVisibleIndices() const;
    // True when the contact's visibility flag is currently unlocked.
    bool isContactVisible(const UICL::Contact &c) const;
    // Popup-local rect of the Back hotspot in directory mode.
    Common::Rect backLabelHitRect() const;
    // Popup-local rect of a visible Back sub-button (subButtons[index]).
    Common::Rect backButtonHitRect(uint subButtonIndex) const;
    // subButtons index of the Back / HOME button visible in the current state,
    // or -1 when none is shown. Used to drive its hover highlight.
    int currentBackButtonIndex() const;
    // subButtons index of the bottom button on a content view.
    uint contentViewBottomButton() const;
    // A browser content view other than the main page (i.e. an actual web page).
    bool isBrowserArticle() const;
    // Move the directory selection by delta, scrolling as needed.
    void moveDirectorySelection(int delta);
    // Scroll the e-mail / search list by one row. These lists have no
    // selection, so the arrows move the list itself.
    void scrollLinkList(int delta);

    Common::Point mouseToChunkCoords(const Common::Point &mouse) const;

    const UICL *_uiclData;

    // Runtime contact list, seeded from _uiclData->contacts and then
    // mutable (AR 130 inserts/replaces entries).
    Common::Array<UICL::Contact> _contacts;

    // Chrome (header.imageName) and sprite atlas (overlayImageName).
    Graphics::ManagedSurface _overlayImage;
    Graphics::ManagedSurface _spritesImage;
    // Nancy 13 camera viewfinder, drawn over the scene while aiming.
    Graphics::ManagedSurface _cameraViewImage;

    bool _closeButtonHovered = false;
    bool _scrollUpHovered = false;
    bool _scrollDownHovered = false;
    // Green-arrow highlight state for the captioned "> HELP" (welcome / dialing)
    // and "< BACK" / HOME sub-buttons: each swaps to its pressed sprite on hover.
    bool _helpButtonHovered = false;
    bool _backButtonHovered = false;

    ScreenState _screenState = kWelcome;

    // Dialed digits as '0'..'9' chars; convert with `c - '0'` to get
    // the slot index that matches a contact's dial prefix.
    Common::String _dialedNumber;

    SoundDescription _callSound;

    // Resolved during kLookupContact, valid through kWaitPickup; -1 = miss.
    int _resolvedContact = -1;

    int _hoveredSlot = -1;

    // Dial-pad slot currently held down (shows the lit / depressed key), or -1.
    int _pressedSlot = -1;

    // Online-hub option button under the cursor (subButtons index 3 = mail,
    // 4 = browser), drawn with its highlighted sprite; -1 = none.
    int _hoveredHubButton = -1;

    // A call queued by auto-dial / Talk, waiting for the key's DTMF tone to
    // finish before entering kPlaceCall (see updateGraphics).
    bool _autoDialPending = false;

    // First visible deduplicated contact, and the active row within the page.
    uint _directoryScroll = 0;
    uint _directorySelection = 0;

    // Nancy 13 "view pictures": index of the currently displayed captured photo.
    int _pictureIndex = 0;

    // Nancy 13 camera framing state.
    bool _inCameraFraming = false;
    Common::Rect _savedPhoneRect;      // phone rect to restore when framing ends
    Common::Point _framingMouse;       // last mouse pos (screen coords)

    // The original caps the persisted camera roll at 50 pictures.
    static const uint kMaxPictures = 50;

    // True while the directory is open to pick a recipient for the current photo
    // (reached from the picture-review "Send" button).
    bool _sendingPicture = false;

    // Active tile + return target for the transient kMessageScreen state.
    const Common::Rect *_messageTileSrc = nullptr;
    ScreenState _messageReturnState = kWelcome;

    // Content-view (single email / page) state.
    ScreenState _contentReturnState = kOnlineHub;
    const UICL::SrcDestRectPair *_contentHeading = nullptr;
    Common::String _contentKey;
    // Uppercased key of the main browser page (empty until the browser is opened).
    Common::String _browserHomeKey;
    uint _contentScroll = 0;

    // Email "opening" transition: the visible row whose closed envelope briefly
    // flashes open before the body is shown (-1 = none), the deadline for that
    // transition, and the body CVTX key to open when it fires.
    int _openingEmailRow = -1;
    uint32 _openingEmailTime = 0;
    Common::String _openingEmailKey;

    // In-page hyperlinks: rects (popup-local, recomputed every draw) and
    // the target CVTX key parsed from each <H>...<L> region of the body.
    Common::Array<Common::Rect> _contentHotspots;
    Common::Array<Common::String> _contentHotspotTargets;

    // Cached render of the current content page. Rendering the hypertext is
    // expensive, so it's only rebuilt when the page key changes — scrolling
    // and hover redraws just re-blit a window of the cached surface (fixes the
    // cursor stutter while hovering the scroll arrows).
    Graphics::ManagedSurface _contentCacheSurface;
    Common::String _contentCacheKey;
    uint16 _contentCacheTextHeight = 0;
    Common::Array<Common::Rect> _contentCacheHotspots;
    Common::Array<Common::String> _contentCacheTargets;

    bool _noSignal = false;
    bool _batteryLow = false;

    // Incoming-call destination (set by startIncomingCall, consumed by the
    // kConnected handler once the player has answered).
    SceneChangeDescription _pendingCallScene;
    bool _hasPendingCallScene = false;

    // True while the in-progress / just-finished call was incoming (auto-rung),
    // so AR 128 knows to close the phone afterwards; player-placed calls leave
    // it open. Persists past _hasPendingCallScene, which is consumed on connect.
    bool _callWasIncoming = false;

    SceneChangeDescription _returnScene;
    bool _hasReturnScene = false;
};

} // End of namespace UI
} // End of namespace Nancy

#endif // NANCY_UI_TASKBAR_CELLPHONEPOPUP_H