アットウィキロゴ
Playdate 非公式 開発まとめ wiki
アットウィキロゴ
Playdate 非公式 開発まとめ wiki
ページ一覧

playdate.ui.gridview

gridview は自分でセル描画をオーバーライドして、選択・スクロール・セクション管理をSDK側が持つ「小型のUIレイアウト兼選択管理クラス」です。
それにより、リスト表示やグリッド表示に使うことができます。

drawCell() だけ自作し、selectNextRow() や scrollToCell() などはSDKに任せる、という使い方が基本です。

import文

uiの機能を使うには基本的に以下のimport文が必要です。 
import "CoreLibs/ui"
 

gridviewのプロパティ

needsDisplay: boolean
「gridview を再描画すべきかどうか」を表すフラグです。
drawInRect() を毎フレーム呼ぶ設計なら、あまり意識しなくても動きますが、必要な時だけ描き直したい場合は trueを設定します。 
Playdate公式の推奨は「毎フレーム描画」なので、描画の最適化が必要な場合以外は使う必要はないです。
backgroundImage: NineSlice
セルの背後に描かれる背景画像 を指定します。(下地のみの描画)
指定可能な対象は、playdate.graphics.image または playdate.nineSlice を設定できます。image を渡した場合はタイル状に繰り返して描画され、nineSlice を渡した場合は角や辺を保ったまま伸縮して描画されます。
isScrolling: boolean
gridview が現在スクロールアニメーション中かどうかを判定する「読み取り専用」のプロパティ。
たとえば次のような制御に便利です。
  • スクロール中は決定入力を受けない
  • スクロール中は効果音を重ねない
  • スクロール完了後に詳細パネルを更新する
  • スクロール中だけカーソル演出を変える
scrollEasingFunction: fun(t:number, b:number, c:number, d:number, a?:number, p?:number): number
スクロールアニメーション時に使う イージング関数 です。
基本となるパラメータは function(t, b, c, d) です。利用できる関数は playdate.easingFunctions に多数あり、デフォルトは playdate.easingFunctions.outCubic です。
  • t: いま何ミリ秒進んだか
  • b: スクロール開始位置
  • c: 目的地までの差分 (=終端-開始)
  • d: アニメ全体の時間 (ミリ秒)
特定のイージング関数では a と p が指定可能です

easingAmplitude?: number
scrollEasingFunction() において追加で amplitude を取るイージング関数、たとえば inOutElastic のような関数を使う場合に、その振幅値をここで指定します。
実際の意味
これは「どれくらい大きく弾むか」の制御です。
elastic 系の easing では、振幅が大きいほどオーバーシュート感が強くなります。つまり、スクロール位置が目的地を少し超えてから戻るような見た目を強められます。
いつ必要か
outCubic のような通常 easing では不要です。
amplitude を受け取る easing を自分で設定したときだけ意味が出る、補助パラメータだと考えるのが正確です。

easingPeriod?: number
scrollEasingFunction() において period を取るイージング関数に対して渡す追加パラメータです。
実際の意味
これは elastic 系で言う 揺れの周期です。
値によって「ブルンと1回大きく揺れる」感じにも、「細かく震える」感じにもなります。
注意
これも scrollEasingFunction() がそれを使うタイプでなければ効果がありません。
つまり easingAmplitude と easingPeriod は単独では意味がなく、scrollEasingFunction() の選択に従属するパラメータです。

changeRowOnColumnWrap: boolean
選択の折り返し設定。selectPreviousColumn() と selectNextColumn() で、現在選択が最初または最後の列にいるときの挙動を制御します。
true (デフォルト) なら列端を超えたときに別の行へ移って選択を継続し、false ならその呼び出しは選択に何の影響も与えません。
scrollCellsToCenter: boolean
項目の移動によるスクロールを中央に寄せるかどうか。
true ならスクロール時に可能ならセルを gridview の中央へ寄せるようにし、false ならそのセルが見えるのに必要な最小限だけスクロールします。これは selection セクションでも説明されていて、選択変更がスクロールを伴う場合のデフォルトは「中央寄せ」です。
true の場合
選択を変えたとき、項目を「主役」として見せやすいです。
常にある程度中央へ寄せるので、選択位置が把握しやすく、周囲の前後項目も見やすいです。
false の場合
スクロール量が最小限になります。
画面外に出そうになったときだけ少し動かし、すでに見えているならほとんど動きません。つまり、リスト全体の位置感覚を保ちやすいです。
使い分け
  • true: セルを強調したい、カタログ表示、カード選択
  • false: 長いリスト、設定メニュー、ログ一覧
実務上の感覚
Playdate の縦リストUIでは、false の方が落ち着いて感じる場面が多いです。
一方で複数列グリッドや「今どれを見ているか」を強調したいUIでは true が効きます。公式でもデフォルトは中央寄せ挙動です。

1. 生成

new(cellWidth, cellHeight)
新しい gridview を生成します。 
local gridview = playdate.ui.gridview.new(0, 24) -- 一列リストの生成.
 

引数
  • cellWidth
  • cellHeight
いずれもピクセル単位です。
重要
cellWidth に 0 を渡すと、「各セルがグリッドの横幅いっぱいを使うリスト表示」 になります。
つまり、
  • cellWidth > 0 → 複数列グリッド向け
  • cellWidth == 0 → 一列リスト向け
です。
向いている用途
  • セーブスロット一覧
  • アイテム一覧
  • 縦リストメニュー
  • タイル状の選択UI

2. 描画まわり

gridview:drawCell(section, row, column, selected, x, y, width, height)
セル描画を自分で実装するためのオーバーライド用メソッドです。
SDK側がセルごとにこの関数を呼ぶので、その中で実際の見た目を描きます。 
function gridview:drawCell(section, row, column, selected, x, y, width, height)
    if selected then
        gfx.fillRoundRect(x, y, width, height, 4)
        gfx.setImageDrawMode(gfx.kDrawModeFillWhite)
    end
    gfx.drawText("Row " .. row, x + 6, y + 4)
    gfx.setImageDrawMode(gfx.kDrawModeCopy)
end
 

引数
  • section
  • row
  • column
  • selected : 現在選択中なら true
  • x, y, width, height : そのセルの描画領域
説明
これが gridview の中核です。
gridview はレイアウトと選択管理は持っていますが、セルの中身は自分で描く設計です。
例えば、
  • 行番号を描く
  • アイコンと文字列を描く
  • selected なら反転や枠を描く
などをここで行います。

gridview:drawHorizontalDivider(x, y, width, height)
横ディバイダの描画をカスタマイズするためのオーバーライド用メソッドです。
呼ばれる条件
  • ディバイダ高さが 0 より大きい
  • かつ、少なくとも1つ divider が追加されている
説明
セルの区切り線、余白付きの線、装飾バーなどを自由に描けます。
単なる線だけでなく、
  • セクション区切り風の太線
  • ドット線
  • 空白込みの区切り
もここで可能です。

gridview:drawSectionHeader(section, x, y, width, height)
セクションヘッダの描画を自分で実装するためのオーバーライド用メソッドです。
呼ばれる条件
ヘッダ高さが 0 より大きい場合のみです。
用途
  • A/B/C のカテゴリ見出し
  • 「装備」「消耗品」などの分類タイトル
  • 日付グループの見出し
drawCell() が行本体、drawSectionHeader() が見出し行です。

gridview:drawInRect(x, y, width, height)
指定した矩形領域に gridview 全体を描きます。

プロパティのneedsDisplay を trueに設定すると、この描画関数の呼び出しが不要となります。

3. ディバイダ管理

gridview:addHorizontalDividerAbove(section, row)
指定した行の上に横ディバイダを追加します。
向いている用途
  • 特定行の前に区切りを入れる
  • グループの境目を強調する
  • 一覧の中で見出し的な区切りを挟む
注意
見た目そのものは drawHorizontalDivider() と高さ設定に依存します。

gridview:removeHorizontalDividers()
追加した横ディバイダをすべて削除します。
向いている用途
  • リスト内容更新時のリセット
  • フィルタ切替後の再構築
  • 状態遷移に応じて区切りを消す

gridview:getHorizontalDividerHeight()
横ディバイダの現在の高さを返します。

gridview:setHorizontalDividerHeight(height)
横ディバイダの高さを設定します。
既定値
stub.lua では、デフォルトは「セル高さの半分」とあります。
意味
これは単なる線の太さというより、区切り用に消費する縦スペースです。
高さを大きくすると、区切り線というより「余白付きセパレータ」に近づきます。

4. セル位置・範囲の取得

gridview:getCellBounds(section, row, column, gridWidth?)
指定セルの矩形範囲を返します。
戻り値
  • x
  • y
  • width
  • height
重要
この矩形は padding を含まない セル本体の範囲です。
また、座標は gridview の左上基準の相対座標 です。
gridWidth が必要な場合
cellWidth == 0 のリスト型では、セル幅が「実際に描くグリッド幅」に依存します。
そのため gridWidth を渡す必要があります。
向いている用途
  • 選択中セルの外側に独自の枠を描きたい
  • セル上に補助UIを出したい
  • セル位置に合わせて別要素を配置したい

5. 列・行・セクションの管理

gridview:getNumberOfColumns()
列数を返します。
デフォルトは 1 です。

gridview:setNumberOfColumns(num)
列数を設定します。
向いている用途
  • 1列リスト → 2列グリッド切替
  • アイコン一覧を複数列で表示
  • メニューのレイアウト変更
注意
列数を増やしてもセルの中身は自動調整されません。
見た目は drawCell() 側も含めて整える必要があります。

gridview:getNumberOfSections()
セクション数を返します。

gridview:setNumberOfSections(num)
セクション数を設定します。
重要
各セクションは少なくとも1行持つ前提で、
行番号は各セクション内で1から始まる構造です。
向いている用途
  • 複数カテゴリのリスト
  • 見出し付き一覧
  • ページ内グループ分け

gridview:getNumberOfRowsInSection(section)
指定セクションの行数を返します。

gridview:setNumberOfRowsInSection(section, num)
指定セクションの行数を設定します。
向いている用途
  • セクションごとに項目数が違う場合
  • カテゴリごとのデータ件数に応じて設定

gridview:setNumberOfRows(...)
複数セクション分の行数をまとめて設定する便利関数です。 
gridview:setNumberOfRows(3, 5, 2)
 
なら、
  • section 1 に 3 行
  • section 2 に 5 行
  • section 3 に 2 行
という意味になります。

用途
  • 一列リストの行数設定
  • 複数セクションの行数を一度に渡す
一列リスト用途
section 1 だけ使うなら、単に
gridview:setNumberOfRows(20)
で 20 行のリストになります。

6. 選択状態の取得・設定

gridview:getSelection()
現在選択されているセルを返します。
戻り値
  • section
  • row
  • column
実務上の意味
決定ボタンを押したときに、どのセルが選ばれているか知るための基本関数です。

gridview:setSelection(section, row, column)
指定セルを選択状態にします。
向いている用途
  • 初期選択位置を設定
  • メニュー再表示時に前回位置を復元
  • 外部入力に応じて選択を飛ばす

gridview:getSelectedRow()
一列リスト向けの便利関数です。
section 1 の選択行を返します。
位置づけ
list-style gridview のショートカットです。

gridview:setSelectedRow(row)
一列リスト向けの便利関数です。
section 1 の指定行を選択します。

7. 選択移動

gridview:selectNextRow(wrapSelection, scrollToSelection?, animate?)
現在選択しているセルを下に移動します。
上に移動する場合は selectPreviousRow() です。
引数
  • wrapSelection
  • scrollToSelection?
  • animate?
意味
  • wrapSelection == true なら最後の行から先頭へ回り込める
  • scrollToSelection を省略または true にすると新しい選択位置へスクロール
  • animate を省略または true にするとそのスクロールがアニメ付き

gridview:selectPreviousRow(wrapSelection, scrollToSelection?, animate?)
現在選択しているセルを上に移動します。
下に移動する場合は selectNextRow() です。

gridview:selectNextColumn(wrapSelection, scrollToSelection?, animate?)
現在選択しているセルを右に移動します。
左に移動する場合は selectPreviousColumn() です。
特に重要な点
最後の列で wrapSelection == true の場合、反対側に回り込みます。
さらに gridview の changeRowOnColumnWrap プロパティ が true なら、回り込み時に行も進む/戻る動作になります。
実務上の意味
2列以上のメニューで横移動したいときの基本です。
折り返しの挙動の制御
項目の移動による折り返しの挙動を制御したい場合は、プロパティの changeRowOnColumnWrap を使用します。

gridview:selectPreviousColumn(wrapSelection, scrollToSelection?, animate?)
現在選択しているセルを左へ移動します。
右に移動する場合は selectNextColumn() です。

項目の移動による折り返しの挙動を制御したい場合は、プロパティの changeRowOnColumnWrap を使用します。

8. スクロール取得・設定

gridview:getScrollPosition()
現在のスクロール位置を返します。
戻り値
  • x
  • y
実務上の意味
  • スクロール位置保存
  • UIの同期
  • 特殊演出や外部表示との連携

gridview:setScrollPosition(x, y, animated?)
スクロール位置を直接設定します。
animatedについて
animated が true か省略時は、scrollEasingFunction と setScrollDuration() の設定でアニメします。
向いている用途
  • 特定位置へジャンプ
  • 外部のカメラやページ位置と同期
  • 独自操作でスクロール制御

gridview:setScrollDuration(ms)
スクロールアニメの時間を設定します。デフォルトは "250ms" です。
向いている用途
  • メニューをキビキビ動かしたい
  • ゆっくり見せたい
  • 画面のテンポ調整

gridview:scrollToTop(animated?)
グリッド先頭までスクロールします。
向いている用途
  • フィルタ変更時に先頭へ戻す
  • メニュー再表示時に頭から見せる

gridview:scrollToCell(section, row, column, animated?)
指定セルが見えるようになるだけスクロールします。
scrollCellToCenter() との違い
  • scrollToCell() は「見えるだけでよい」
  • scrollCellToCenter() は「可能なら中央に持っていく」
最小限の移動で済ませたいならこの関数です。

gridview:scrollCellToCenter(section, row, column, animated?)
指定セルが可能な限り中央に来るようにスクロールします。
向いている用途
  • 選択対象を強調したい
  • 周囲の文脈も見せたい
  • 詳細表示と連動するUI

gridview:scrollToRow(row, animated?)
一列リスト向けの便利関数です。
section 1 の指定行が見える位置までスクロールします。

9. セル・コンテンツ・ヘッダの余白設定

gridview:setCellPadding(left, right, top, bottom)
各セルの内側余白を設定します。
意味
drawCell() に渡す「x, y, width, height」は、この padding を考慮した範囲になります。
向いている用途
  • 文字がセル端に張り付くのを防ぐ
  • アイコンとテキストに余裕を持たせる
  • 選択枠と中身の間に余白を作る

gridview:setContentInset(left, right, top, bottom)
gridview 全体の内容を、外枠からどれだけ内側に寄せるか設定します。
向いている用途
  • 背景枠画像の内側に内容を収める
  • 画面端にベタ付きを避ける
  • 独自ボーダー分の余白確保
setCellPadding() との違い

gridview:setCellSize(cellWidth, cellHeight)
セルサイズを変更します。
作成後のリサイズ用です。
重要
cellWidth == 0 にすると横幅いっぱいのリスト型になります。

gridview:getSectionHeaderHeight()
現在のセクションヘッダ高さを返します。

gridview:setSectionHeaderHeight(height)
セクションヘッダの高さを設定します。
デフォルトは 0 で、0 の場合はヘッダは描かれません。
向いている用途
  • セクション見出しを有効化
  • カテゴリごとのラベル帯を出す

gridview:setSectionHeaderPadding(left, right, top, bottom)
セクションヘッダ内部の余白を設定します。
実務上の意味
drawSectionHeader() の描画スペースに余裕を持たせるための設定です。

補足

便利な考え方
gridview は内部的にだいたいこう分かれます。
データ量の設定
  • setNumberOfSections()
  • setNumberOfRows()
  • setNumberOfRowsInSection()
  • setNumberOfColumns()
見た目の枠組み設定
  • setCellSize()
  • setCellPadding()
  • setContentInset()
  • setSectionHeaderHeight()
  • setSectionHeaderPadding()
  • setHorizontalDividerHeight()
自作描画
  • drawCell()
  • drawSectionHeader()
  • drawHorizontalDivider()
状態操作
  • setSelection()
  • setSelectedRow()
  • getSelection()
  • getSelectedRow()
ナビゲーション
  • selectNextRow()
  • selectPreviousRow()
  • selectNextColumn()
  • selectPreviousColumn()
スクロール制御
  • drawInRect()
  • getScrollPosition()
  • setScrollPosition()
  • setScrollDuration()
  • scrollToCell()
  • scrollCellToCenter()
  • scrollToRow()
  • scrollToTop()

よくある最小構成
かなり典型的なのはこれです。 
local gfx = playdate.graphics
local gridview = new(0, 24)
gridview:setNumberOfRows(10)
gridview:setCellPadding(4, 4, 2, 2)
function gridview:drawCell(section, row, column, selected, x, y, width, height)
    if selected then
        gfx.fillRoundRect(x, y, width, height, 4)
        gfx.setImageDrawMode(gfx.kDrawModeFillWhite)
    end
    gfx.drawText("Item " .. row, x + 4, y + 3)
    gfx.setImageDrawMode(gfx.kDrawModeCopy)
end
function playdate.update()
    gfx.clear()
    if playdate.buttonJustPressed(playdate.kButtonUp) then
        gridview:selectPreviousRow(true)
    elseif playdate.buttonJustPressed(playdate.kButtonDown) then
        gridview:selectNextRow(true)
    end
    gridview:drawInRect(20, 20, 200, 180)
end
 
これで、かなり「Playdateの標準メニュー」らしいものが作れます。

関数以外の重要なプロパティ
gridview には関数以外にも重要なメンバーがあります。
特に挙動面で大きいのは次です。

これらは selectNextColumn() や setScrollPosition() の挙動に関わります。

関連ページ

「playdate.ui.gridview」をウィキ内検索
最終更新：2026年04月19日 16:12